API Error Codes Reference
Stable, machine-readable error codes for programmatic handling. These codes are part of the public API and will not change without versioned deprecation.
Proxy Error Codes (JSON-RPC)
These are returned in the JSON-RPC error object or as HTTP error responses.
| Code |
HTTP Status |
Constant |
Description |
| -32010 |
402 |
INSUFFICIENT_CREDITS |
Credit balance too low. Deposit USDC. |
| -32005 |
429 |
RATE_LIMITED |
Per-second rate limit exceeded. Check Retry-After header. |
| -32005 |
429 |
CONCURRENCY_LIMITED |
Too many concurrent in-flight requests. |
| -32003 |
502 |
BACKEND_UNAVAILABLE |
Upstream Solana RPC node unreachable. |
| -32001 |
403 |
METHOD_NOT_ALLOWED |
Method is denied (e.g., requestAirdrop). |
| -32002 |
403 |
RESERVED |
Reserved legacy code; current access is credit-gated, not plan-gated. |
| -32004 |
200 |
SERVICE_PROFILE_DISABLED |
Endpoint profile does not enable the requested archive/history or heavy-indexed service. No credits are consumed. |
| -32003 |
503 |
SERVICE_TEMPORARILY_UNAVAILABLE |
Transient service unavailability, including startup, dependency failure, overload, or critical disk pressure. No credits are consumed when rejected before billing. |
Note: -32005 is used for both rate limiting and concurrency limiting. Distinguish by the error message text: "rate limit exceeded" vs "concurrency limit exceeded".
Standard JSON-RPC Error Codes
| Code |
Description |
| -32700 |
Parse error: invalid JSON |
| -32600 |
Invalid request: missing required fields |
| -32601 |
Method not found |
| -32602 |
Invalid params |
| -32603 |
Internal error |
Solana Node Error Codes
These pass through from the upstream Agave node:
| Code |
Description |
| -32001 |
Node is behind by N slots |
| -32002 |
Transaction simulation failed |
| -32003 |
Transaction signature verification failure |
| -32004 |
Block not available (purged) |
| -32005 |
Node is unhealthy |
| -32007 |
Long-running operation (timeout) |
| -32009 |
Slot was skipped |
| -32014 |
Minimum slot not reached |
| -32015 |
Unsupported transaction version |
HTTP Status Codes
| Status |
Meaning |
| 200 |
Success (may still contain JSON-RPC error) |
| 400 |
Bad request (malformed body) |
| 401 |
Authentication failed |
| 402 |
Insufficient credits |
| 403 |
Forbidden (denied method, account suspension, nonce reuse) |
| 404 |
Account not found |
| 429 |
Rate limited |
| 500 |
Internal server error |
| 502 |
Backend RPC unavailable |
| 503 |
Service temporarily unavailable |
| 504 |
Gateway timeout |
Every successful response includes:
| Header |
Description |
| X-Credits-Remaining |
Current credit balance after this request |
| X-Credits-Low |
Present and set to "true" when balance < 1000 |
Rate limit responses (429) include:
| Header |
Description |
| Retry-After |
Seconds to wait before retrying |
| X-Ratelimit-Limit |
Maximum requests per second for this account |
| X-Ratelimit-Remaining |
Remaining requests in current window |
| X-Ratelimit-Reset |
Unix timestamp when the rate limit resets |
WebSocket Close Codes
| Code |
Reason |
Description |
| 1000 |
normal |
Clean close by client |
| 1008 |
policy_violation |
Invalid or expired token |
| 4001 |
auth_failed |
WebSocket authentication failed |
| 4002 |
insufficient_credits |
Credit balance below minimum (10) |
| 4003 |
rate_limited |
Too many messages per second |