Errors
This page lists the errors returned by our services and what to do about each one. The short rule: retry temporary errors with backoff, never retry authentication errors in a loop.
Private TPU Send (HTTPS, JSON-RPC)
Errors are returned as a JSON-RPC error object together with an HTTP status code.
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32029, "message": "rate limit exceeded" } }| HTTP | JSON-RPC code | Meaning | What to do |
|---|---|---|---|
| 400 | -32700 | The body is not valid JSON | Fix the request |
| 400 | -32600 | Not a valid JSON-RPC 2.0 request | Fix the request |
| 400 | -32601 | Unknown method | Use sendTransaction or getHealth |
| 400 | -32602 | Invalid parameters: the transaction cannot be decoded, the encoding is wrong or the transaction is larger than 1,232 bytes | Check the base64 encoding and the size |
| 401 | -32001 | Missing or invalid API key | Check the x-api-key header. Do not retry |
| 403 | -32003 | IP address not allowlisted, or the product is not part of your offer | Check your server's public IP address, contact support. Do not retry |
| 429 | -32029 | TPS limit exceeded. The transaction was not forwarded | Pause briefly and resend. Rate-limit on your side |
| 503 | -32005 | Temporarily unavailable, for example during maintenance | Retry with backoff. Use a fallback send path if the outage lasts |
What is not reported at submission
Private TPU Send does not simulate transactions, so it accepts any well-formed signed transaction. The following problems show up only later, through your RPC:
- Expired blockhash. The leader drops the transaction and it never appears on-chain. If a signature never shows up, check the blockhash first.
- Insufficient balance for fees. The transaction is dropped without a trace.
- Program errors, such as slippage limits or insufficient funds in a swap. The transaction lands in a block, pays its fee and is marked as failed.
getSignatureStatusesreports the error.
Simulate through your RPC before sending to catch these early. See Private TPU Send.
gRPC status codes
These codes apply to gRPC connections you open, such as Shreds. For Private Orderflow over gRPC, our relayer connects to your server, so connection problems show up in your server's logs. See Troubleshooting.
| Status | Meaning | Retry? |
|---|---|---|
UNAUTHENTICATED | Missing or invalid API key | No. Check the x-api-key metadata |
PERMISSION_DENIED | IP address not allowlisted, or the product is not part of your offer | No. Contact support |
RESOURCE_EXHAUSTED | Too many concurrent connections for your API key | After closing unused connections, with backoff |
UNAVAILABLE | The endpoint is restarting or the network path is interrupted | Yes, reconnect with backoff |
DEADLINE_EXCEEDED | A deadline set by your client expired | Do not set deadlines on streaming calls |
INTERNAL, UNKNOWN | Unexpected server-side error | Yes, reconnect with backoff. Report it if it repeats |
A stream that ends without an error status was closed by the server, for example before maintenance. Reconnect with backoff.
WebSocket
Errors during the connection upgrade:
| HTTP | Meaning | Retry? |
|---|---|---|
| 401 | Missing or invalid API key | No |
| 403 | IP address not allowlisted, or the product is not part of your offer | No |
| 429 | Too many concurrent connections for your API key | After closing unused connections, with backoff |
Close codes of an open connection:
| Code | Meaning | Retry? |
|---|---|---|
| 1000 | Normal closure | Yes, if you did not close the connection yourself |
| 1001 | The server is going away, for example a restart or maintenance | Yes, with backoff |
| 1008 | Policy violation: the API key was revoked or suspended | No. Contact support |
| 1011 | Unexpected server-side error | Yes, with backoff |
| 1013 | The server is temporarily overloaded | Yes, with backoff |
| 4008 | Slow consumer: your client did not read messages fast enough and the send buffer overflowed | Yes, after fixing the consumer. See Limits |
Always log the close code and reason. Our support needs them to investigate a disconnect.
Retry policy
| Retry with backoff | Do not retry automatically |
|---|---|
| HTTP 429 and 503 | HTTP 400, 401 and 403 |
gRPC UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL, UNKNOWN | gRPC UNAUTHENTICATED and PERMISSION_DENIED |
| WebSocket close codes 1000, 1001, 1011, 1013 and 4008 | WebSocket close code 1008 |
Use exponential backoff with jitter, for example 500 milliseconds doubled on every attempt, capped at 30 seconds, plus a random delay of up to 250 milliseconds. Reset the delay after a connection has been stable for a minute.
If an error persists, see Troubleshooting or contact our support: @ZoriDev.
Need help or access? Contact our support on Telegram.
Contact