Errors
Predictable HTTP status codes and machine-readable error codes on every failure.
Error shape
Every non-2xx response has the same body:
{
"error": {
"code": "invalid_address",
"message": "\"abc123\" is not a valid Solana address. Addresses are 32–44 base58 characters.",
"details": { "address": "abc123" }
}
}| Field | Type | Description |
|---|---|---|
code | string | Stable, machine-readable identifier. Branch on this, not on message. |
message | string | Human explanation of what went wrong and, where possible, how to fix it. |
details | object | Optional structured context (the offending parameter, limits, etc.). |
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_address | A path or body parameter isn't a valid Solana address. |
| 400 | invalid_signature | Not a valid transaction signature. |
| 400 | invalid_transaction | The submitted transaction couldn't be decoded (expects base64). |
| 400 | invalid_parameter | A query or body parameter has the wrong type or an out-of-range value. |
| 400 | unsupported_confirmation | This endpoint doesn't support the requested confirmation level. |
| 400 | cursor_expired | The pagination cursor is no longer valid — restart from a checkpoint. |
| 401 | unauthorized | Missing or invalid API key. |
| 404 | not_found | The account, transaction, or token doesn't exist at the requested confirmation level. |
| 409 | blockhash_expired | The transaction's blockhash lapsed before it could land. Rebuild and re-sign. |
| 422 | simulation_failed | Preflight simulation failed — the response includes program logs in details.logs. |
| 429 | rate_limited | Too many requests. Back off; see headers below. |
| 500 | internal_error | Something failed on our side. Safe to retry with backoff. |
| 503 | upstream_unavailable | The blockchain network or upstream infrastructure is degraded. Retry with backoff. |
Rate limit headers
Every response includes your current standing:
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 46
X-RateLimit-Reset: 1754300400On 429, a Retry-After header tells you how many seconds to wait.
Retry guidance
- Safe to retry:
429,500,503— with exponential backoff and jitter. - Retry after rebuilding:
blockhash_expired— fetch a fresh blockhash, re-sign, resubmit. (The send endpoint manages retries within the blockhash window for you.) - Don't retry:
4xxvalidation errors — fix the request first.