# Errors

> Understand a rejected request and what to change before sending again.

<Note>
Supanode issues keys through [Telegram](https://telegram.me/supanode_tgs). Default minimum tip: 0.001 SOL; default rate: 15 sends/s per key per metro. Your key settings can differ. Declared tips are off by default and require enablement and a payment arrangement with Supanode. If your key returns `partner_declared_tips`, use an on-chain transfer instead.
</Note>

Match on the stable `reason`; the wording of `message` can change. JSON-RPC returns the details in
`error.data`; raw HTTP returns them in the response body. QUIC includes the same
JSON in their rejection detail.

The `docs` field is optional and is omitted on hosted Supanode domains.

`retryable: true` means the request can succeed later without changing its contents.
Wait before retrying and make sure the transaction has not expired. If the outcome is
unknown, [check its signature](https://supanode.xyz/docs/solana/sender/confirmation) before sending a replacement.

## Response codes

JSON-RPC can return an error with HTTP 200, so always read the response body.

| Reason | Raw HTTP | JSON-RPC HTTP | JSON-RPC code | QUIC code |
| --- | --- | --- | --- | --- |
| `unauthorized` | 401 | 401 | -32000 | 8 |
| `key_paused` | 401 | 401 | -32000 | 8 |
| `rate_limited` | 429 | 429 | -32001 | 1 |
| `malformed` | 400 | 200 | -32602 | 4 |
| `too_large` | 413 | 200 | -32602 | 5 |
| `unsigned` | 400 | 200 | -32602 | 2 |
| `signature_count` | 400 | 200 | -32602 | 7 |
| `missing_tip` | 400 | 200 | -32602 | 3 |
| `credit_exhausted` | 400 | 200 | -32602 | 3 |
| `simulation_failed` | 400 | 200 | -32002 | 9 |
| `bundle_size` | 400 | 200 | -32602 | 10 |
| `bundle_control` | 400 | 200 | -32602 | 10 |
| `unsupported` | 404 or 403 | 200 or 403 | -32601 | 4 or 10 |
| `not_ready` | 503 | 503 | -32603 | 11 |
| `overloaded` | 503 | 503 | -32603 | 11 |
| `forward_failed` | 503 | 503 | -32603 | 6 |
| `preflight_unavailable` | 503 | 503 | -32603 | 12 |
| `internal` | 503 | 503 | -32603 | 12 |
| `payment_required` | 402 | 402 | -32003 | 13 |
| `invalid_request` | 400, 404 or 408 | 200 | Depends on `problem` | 4 |

A QUIC code of `0` means accepted. See [QUIC](https://supanode.xyz/docs/solana/sender/reference/quic) for framing, and [`getHealth`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/health) for its separate unhealthy response.

<span id="unknown-host" />

### Unknown or removed hostname

HTTPS checks TLS SNI and each request's `Host` or `:authority` against the current
served hostnames. An unknown or removed name receives HTTP 421 with a plain-text
body and no JSON-RPC envelope or rejection object. QUIC closes the connection
with application code 4 and reason text `unknown host`.

After a domain removal reaches a server, existing connections and resumed TLS
sessions cannot keep using it. Switch to a current endpoint before removal.

## Unauthorized

Supply a valid API key using the [authentication method](https://supanode.xyz/docs/solana/sender/api-keys) for
your interface. Repeating the same unauthorized request will not help.

<span id="key_paused" />

## Key paused

The key is paused. It works again when it's resumed, with the same secret. If your
provider issued the key, contact them. For your team's own keys,
ask us to resume them through [Supanode on Telegram](https://telegram.me/supanode_tgs).

<span id="rate_limited" />

## Rate limited

Reduce your send rate. `limit` identifies transactions or bundles; `per_second` gives
the quota when included. Wait for `retry_after_ms`, if present, before trying again.

## Malformed

The encoding, transaction or request format is invalid. Read `problem` and `message`
to find the failed check. For bundles, `index` identifies the affected transaction.

`tip_overflow` means the qualifying tip sum exceeds an unsigned 64 bit integer.
`tip_too_large` means the qualifying tip total exceeds 2 SOL.
`duplicate_signature` means a bundle repeats a transaction signature; `index` identifies the repeated member.

<span id="too_large" />

## Too large

Reduce the payload to the reported byte `limit`. `size` and a bundle `index` are included
when known. See [transaction limits](https://supanode.xyz/docs/solana/sender/send) and [bundle limits](https://supanode.xyz/docs/solana/sender/bundles).

## Unsigned

Sign the transaction before sending it. `index` identifies the transaction in a bundle.

<span id="signature_count" />

## Signature count

Sign with every required signer. `required` and `present`, when included, show the
mismatch; `index` identifies the transaction in a bundle.

<span id="missing_tip" />

## Missing tip

Include a sufficient tip to a [Supanode tip account](https://supanode.xyz/docs/solana/sender/tips#tip-accounts). `minimum` is the
required amount in lamports and `found` is the amount recognized. Increase the transfer
if needed. A declared tip requires that option to be enabled for your key.

<span id="credit_exhausted" />

## Credit exhausted

The declared tip exceeds the credit available on your key. Include the tip in the
transaction instead, or ask about billing on [Supanode on Telegram](https://telegram.me/supanode_tgs). `declared` and
`available` give the amounts in lamports.

<span id="simulation_failed" />

## Simulation failed

Preflight found an execution error. Inspect `error` and the returned simulation logs,
fix the transaction and sign it again before resubmitting.

<span id="bundle_size" />

## Bundle size

Submit between one and four transactions. `count` shows the submitted number and `limit`
the maximum. A JSON-RPC batch is not a bundle.

<span id="bundle_control" />

## Bundle control

The transaction at `index` violates a [bundle control rule](https://supanode.xyz/docs/solana/sender/bundles). `rule`
identifies the required change:

| Rule | Change |
| --- | --- |
| `first_only` | Put the transaction carrying the control account first. |
| `one_only` | Use the control account in only one transaction. |
| `default_programs_only` | After the first transaction, use only System, Compute Budget and Memo instructions. |

<span id="unsupported" />

## Unsupported feature

The interface or your key does not support this request. For
`feature: bundles`, bundles are turned off for this key; use [Supanode on Telegram](https://telegram.me/supanode_tgs) to discuss access.

For `feature: partner_declared_tips`, remove the declared tip and send an on-chain tip to a [Supanode tip account](https://supanode.xyz/docs/solana/sender/tips#tip-accounts). It returns HTTP 403 and
QUIC code 4. Direct bundle declarations use `feature: declared_tips`, HTTP 403 and
code 10; remove the declaration and pay the required bundle tip inside the transactions.

<span id="not_ready" />

## Not ready

Wait and retry, or use another metro's host. `waiting_for` gives more context:

| Value | Action |
| --- | --- |
| `leader_route` | Try again shortly or use another metro's host. |
| `block_engine` | Bundles are temporarily unavailable. Retry rather than split a bundle that must land together. |
| `blockhash` | Try again shortly. |
| `declared_tips` | Include a tip transfer or retry later. |
| `tip_vaults` | Tip processing is temporarily unavailable. Try again shortly. |

## Overloaded

Retry after a delay or use another metro's host, while the transaction remains valid.

<span id="forward_failed" />

## Forward failed

Submission failed. Check the transaction's status if the outcome is unknown, then retry
while it remains valid.

<span id="preflight_unavailable" />

## Preflight unavailable

Simulation is temporarily unavailable. Retry later. You can explicitly skip preflight
if your application accepts sending without simulation.

<span id="internal" />

## Internal error

Retry after a delay. If the problem persists, report it on [Supanode on Telegram](https://telegram.me/supanode_tgs) with the metro,
UTC time and request details, without credentials.

<span id="payment_required" />

## Payment required

An overdue payment has suspended sending for this key. Resolve the payment or
ask for help on [Supanode on Telegram](https://telegram.me/supanode_tgs). `unpaid_lamports` gives the outstanding amount. Repeated
submissions do not clear the suspension.

<span id="invalid_request" />

## Invalid request

Correct the JSON-RPC request using `problem` and `message`:

| Problem | JSON-RPC code | Change |
| --- | --- | --- |
| `parse_error` | -32700 | Send valid JSON. |
| `not_found` | -32600 | Use a supported route. |
| `body_timeout` | -32600 | Complete the request body before the deadline. |
| `body_unreadable` | -32600 | Check the connection and request body. |
| `batch` | -32600 | Send one request, or use `sendBundle`. |
| `not_json_rpc` | -32600 | Set `jsonrpc` to `2.0`. |
| `unknown_method` | -32601 | Use a method in the [JSON-RPC reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc) |
| `missing_params` | -32602 | Supply the required parameters. |
| `invalid_params` | -32602 | Use the documented parameter array. |
| `transaction_not_string` | -32602 | Encode the transaction as a string. |
| `invalid_options` | -32602 | Correct the options and field types. |
| `invalid_commitment` | -32602 | Use `processed`, `confirmed` or `finalized`. |

Only `body_timeout` and `body_unreadable` are retryable without changing the request.

## Payment errors

For problems with an enabled declared-tip billing integration, the following reasons
may be reported. An error does not mean a payment completed. Ask for help on [Supanode on Telegram](https://telegram.me/supanode_tgs) if you
cannot resolve the payment through your configured integration.

<span id="no_open_invoice" />

### No open invoice

There is no outstanding invoice for this key. Do not submit another payment.

<span id="wrong_amount" />

### Wrong amount

The payment does not match the invoice. Use the invoiced amount.

<span id="foreign_instruction" />

### Foreign instruction

The payment transaction includes unsupported instructions. Check the billing integration.

<span id="bad_transfer" />

### Bad transfer

The payment's recipient or signer is invalid. Check the payment details.

<span id="nothing_transferred" />

### Nothing transferred

The transaction does not include the required payment.

<span id="stale_blockhash" />

### Stale blockhash

The payment transaction is no longer valid. Create a fresh payment through your integration.

<span id="simulation_unavailable" />

### Simulation unavailable

A payment check is temporarily unavailable. Try again later.

<span id="settlement_in_flight" />

### Settlement in flight

A payment is processing. Wait for its result before submitting another.

<span id="already_used" />

### Already used

This payment was already used. Do not send it again.

<span id="not_sent" />

### Not sent

The payment could not be submitted. Try again later.

<span id="failed_on_chain" />

### Failed on chain

The payment failed on chain. Check its execution error and wait for a new payment request before signing another transfer.

<span id="settlement_expired" />

### Settlement expired

The payment transaction expired without a recorded payment. Wait for a new payment request before signing another transfer.

<span id="invalid_message" />

### Invalid message

The payment request is invalid. Check the billing integration.

<span id="ledger_unavailable" />

### Ledger unavailable

The payment could not be processed. Try again later.
