Error Handling
When working with Syndica's Solana RPC API, you may encounter HTTP status codes and JSON-RPC error codes. This guide explains common errors and how to resolve them.
HTTP Status Codes
HTTP status codes indicate the result of your request at the transport layer. You'll see these codes in RPC Analytics and application logs.
| HTTP Code | Message | Description | How to Fix |
|---|---|---|---|
| 200 | Success | Request processed successfully | No action needed |
| 401 | Unauthorized | Invalid or missing API key | Verify your API key is correct and not expired |
| 402 | Payment Required | Requires a paid account | Upgrade your plan to access this feature |
| 429 | Rate Limit Exceeded | Too many requests | Reduce request rate, configure custom rate limits, or upgrade your plan |
| 503 | Service Unavailable | Temporary service disruption | Check status.syndica.io and retry |
When you receive a 429 error:
- Implement exponential backoff in your retry logic
- Consider request throttling or debouncing for non-critical calls
- Configure custom rate limits per API key to control usage more precisely
- Upgrade your plan for higher RPS limits
JSON-RPC Error Codes
JSON-RPC errors appear in the response body when the RPC method encounters an issue. Syndica uses custom error codes in addition to standard Solana RPC errors.
Syndica Custom Error Codes
| RPC Code | Error | Description | How to Fix |
|---|---|---|---|
| 7429 | Rate Limited | Method-specific or namespace rate limit exceeded | Check your rate limits and upgrade if needed |
| 7700 | Invalid Headers | Request headers are malformed or invalid | Verify headers match Solana RPC documentation |
| 7701 | Batch Size Exceeded | Batch request contains too many calls | Reduce batch size or upgrade your plan |
| 7702 | Duplicate Subscription | Attempting to create duplicate WebSocket subscription | Use a different subscription or open a new connection |
| 7703 | Subscription Limit Exceeded | Maximum subscriptions per connection reached | Open another WebSocket connection or close unused subscriptions |
Syndica's custom error codes (7xxx) provide more specific information than standard Solana errors, helping you diagnose and resolve issues faster.
Standard JSON-RPC Error Codes
Solana RPC also returns standard JSON-RPC 2.0 error codes:
| RPC Code | Error | Description |
|---|---|---|
| -32700 | Parse error | Invalid JSON |
| -32600 | Invalid Request | Request format is incorrect |
| -32601 | Method not found | Requested method doesn't exist |
| -32602 | Invalid params | Method parameters are incorrect |
| -32603 | Internal error | Server-side processing error |
See the Solana RPC documentation for a complete list of Solana-specific error codes.
Error Response Format
JSON-RPC errors follow this structure:
{
"jsonrpc": "2.0",
"error": {
"code": 7429,
"message": "Rate Limited",
"data": {}
},
"id": 1
}
Troubleshooting Tips
Why am I getting 401 Unauthorized errors?
Common causes:
- API key is missing or incorrect
- API key has been revoked
- API key has expired (if custom expiration was set)
Solution: Generate a new API key from the API Keys page and update your application.
How do I handle rate limit (429) errors?
Best practices:
- Implement exponential backoff with jitter
- Cache responses when possible
- Use WebSocket subscriptions instead of polling
- Upgrade to a higher plan tier for increased limits
See Rate Limits documentation for current limits by plan.
What should I do when I get a 503 Service Unavailable error?
This indicates a temporary issue with Syndica's infrastructure:
- Check status.syndica.io for known issues
- Implement retry logic with exponential backoff
- If the issue persists, contact support
Why are my WebSocket subscriptions failing?
Common issues:
- Reached maximum connections or subscriptions limit
- Trying to create duplicate subscriptions on the same connection
- Invalid subscription parameters
Solution: Review WebSocket limits and verify your subscription parameters.
How can I see error rates in my application?
Use Syndica's built-in monitoring:
- Navigate to Analytics in your dashboard
- View error breakdowns by status code and RPC error code
- Filter by time range to identify patterns
- Check Logs for detailed error messages
See Observability documentation for more details.
What You Can Do Next
- Rate Limits - Understand RPC method rate limits
- Sending Transactions - Optimize transaction success rates
- Observability - Monitor errors in your dashboard
- Solana RPC Docs - Official Solana RPC error reference