Errors
Understand a rejected request and what to change before sending again.
// updated 2026-11-17
Supanode issues keys through Telegram. 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.
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 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 for framing, and getHealth for its separate unhealthy response.
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 for your interface. Repeating the same unauthorized request will not help.
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.
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.
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 Supanode 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 ask about billing on Supanode on Telegram. 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 or your key does not support this request. For
feature: bundles, bundles are turned off for this key; use Supanode on Telegram to discuss access.
For feature: partner_declared_tips, remove the declared tip and send an on-chain tip to a Supanode tip account. 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.
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.
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, report it on Supanode on Telegram with the metro, UTC time and request details, without credentials.
Payment required
An overdue payment has suspended sending for this key. Resolve the payment or
ask for help on Supanode on Telegram. 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 JSON-RPC 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. Ask for help on Supanode on Telegram 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 and wait for a new payment request before signing another transfer.
Settlement expired
The payment transaction expired without a recorded payment. Wait for a new payment request before signing another transfer.
Invalid message
The payment request is invalid. Check the billing integration.
Ledger unavailable
The payment could not be processed. Try again later.