Errors
Understand a rejected request and what to change before sending again.
Match the stable reason, not the wording of message. JSON-RPC returns the details in
error.data; raw HTTP returns them in the response body. QUIC and IPC include the same
JSON in their rejection detail.
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 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/IPC code |
|---|---|---|---|---|
unauthorized | 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 | 200 | -32601 | 4 |
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/IPC code of 0 means accepted. See the relevant API reference for framing
and the separate getHealth response.
Unauthorized
Supply a valid API key using the authentication method for your interface. Repeating the same unauthorized request will not help.
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.
Too large
Reduce the payload to the reported byte limit. size and a bundle index are included
when known. See transaction limits and bundle limits.
Unsigned
Sign the transaction before sending it. index identifies the transaction in a bundle.
Signature count
Sign with every required signer. required and present, when included, show the
mismatch; index identifies the transaction in a bundle.
Missing tip
Include a sufficient tip to a current tip account. 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.
Credit exhausted
The declared tip exceeds the credit available on your key. Include the tip in the
transaction instead, or contact support about billing. declared and
available give the amounts in lamports.
Simulation failed
Preflight found an execution error. Inspect error and the returned simulation logs,
fix the transaction and sign it again before resubmitting.
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.
Bundle control
The transaction at index violates a bundle control rule. 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. |
Unsupported feature
The interface does not support this method. For feature: tip_floor, query a hosted
endpoint rather than the local agent. See getTipFloor.
Not ready
Wait and retry, or use another region. waiting_for gives more context:
| Value | Action |
|---|---|
leader_route | Try again shortly or use another region. |
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. |
upstream | Wait for the local agent to reconnect. |
tip_vaults | Fetch the tip-account list again before retrying. |
Overloaded
Retry after a delay or use another region, while the transaction remains valid.
Forward failed
Submission failed. Check the transaction's status if the outcome is unknown, then retry while it remains valid.
Preflight unavailable
Simulation is temporarily unavailable. Retry later. You can explicitly skip preflight if your application accepts sending without simulation.
Internal error
Retry after a delay. If the problem persists, contact support with the region, UTC time and request details, without credentials.
Payment required
An overdue payment has suspended sending for this key. Resolve the payment or
contact support. unpaid_lamports gives the outstanding amount. Repeated
submissions do not clear the suspension.
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 API reference. |
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. Contact support if you cannot resolve the payment through your configured integration.
No open invoice
There is no outstanding invoice for this key. Do not submit another payment.
Wrong amount
The payment does not match the invoice. Use the invoiced amount.
Foreign instruction
The payment transaction includes unsupported instructions. Check the billing integration.
Bad transfer
The payment's recipient or signer is invalid. Check the payment details.
Nothing transferred
The transaction does not include the required payment.
Stale blockhash
The payment transaction is no longer valid. Create a fresh payment through your integration.
Simulation unavailable
A payment check is temporarily unavailable. Try again later.
Settlement in flight
A payment is processing. Wait for its result before submitting another.
Already used
This payment was already used. Do not send it again.
Not sent
The payment could not be submitted. Try again later.
Failed on chain
The payment failed on chain. Check its execution error before trying again.
Settlement expired
The payment transaction expired. Create a fresh payment through your integration.
Invalid message
The payment request is invalid. Check the billing integration.
Ledger unavailable
The payment could not be processed. Try again later.