Error Codes FAQ

Troubleshoot HTTP error codes when using Helius RPC endpoints - identify and resolve the most common authentication, rate limiting, and server issues

Why am I getting a 401 error?

What this means

401 Unauthorized - Your request lacks valid authentication credentials.

Common causes

• Invalid or missing API key
• API key included in the wrong location
• Access Control Rules blocking your request
• Expired or revoked API key

Solutions

1. Verify your API key format

   https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY
   

2. Check API key placement

   • Ensure the API key is in the query parameters
   • Verify there are no extra spaces or characters

3. Review Access Control Rules

   • Check your dashboard settings for IP restrictions
   • Ensure your domain is allowlisted if using browser requests

For detailed authentication setup, see our Authentication guide.

Why am I getting a 429 error?

What this means

429 Too Many Requests - You’ve exceeded your plan’s rate limits.

Common causes

• Making requests faster than your plan allows
• Burst traffic exceeding instantaneous limits
• Multiple applications sharing the same API key
• Inefficient code making redundant requests

Solutions

1. Monitor your usage

   • Check the Rate Limited Requests graph in your dashboard
   • Review which endpoints are hitting limits

2. Optimize your requests

   • Cache responses when possible
   • Batch multiple operations into single calls
   • Remove unnecessary polling or duplicate requests

3. Implement rate limiting

   • Add delays between requests in your application
   • Use exponential backoff for retries

4. Consider upgrading

   • Review Plans & Rate Limits for higher tiers

Rate limits reset every minute, so temporary throttling usually resolves quickly.

Why am I getting a 500 error?

What this means

500 Internal Server Error - A server-side error occurred while processing your request.

Common causes

• Malformed request payload
• Server experiencing temporary issues
• Invalid parameters causing server errors
• Network connectivity problems

Solutions

1. Validate your request

   • Ensure JSON payload is properly formatted
   • Verify all required parameters are included
   • Check parameter types match the API specification

2. Check service status

   • Visit the Helius Status Page for ongoing issues
   • Look for any reported outages or degraded performance

3. Implement retry logic

   • Wait a few seconds before retrying
   • Use exponential backoff for multiple attempts

4. Get support

   • If errors persist, contact support with your request details
   • Include the exact request payload and timestamp

Server errors are typically temporary and usually resolve automatically.

Why am I getting a 503 error?

What this means

503 Service Unavailable - The server is temporarily overloaded or under maintenance.

Common causes

• High traffic causing temporary overload
• Scheduled maintenance windows
• Server capacity limits reached
• Network infrastructure issues

Solutions

1. Wait and retry

   • Wait 30-60 seconds before trying again
   • This error usually resolves as load balances

2. Implement smart retries

   • Use exponential backoff (start with 1s, then 2s, 4s, etc.)
   • Set a maximum retry limit (3-5 attempts)
   • Add jitter to avoid thundering herd effects

3. Check for maintenance

   • Review the Helius Status Page for scheduled maintenance
   • Plan around announced maintenance windows

4. Distribute load

   • If possible, spread requests over time
   • Avoid burst patterns that can trigger overload protection

503 errors are designed to be temporary - the service automatically recovers as server load decreases.

Why am I getting a 504 error?

What this means

504 Gateway Timeout - The server didn’t receive a response from upstream services within the timeout period.

Common causes

• Network connectivity issues
• Complex operations exceeding timeout limits
• Slow blockchain responses during high network congestion
• Large data requests taking too long to process

Solutions

1. Check your connection

   • Verify your internet connection is stable
   • Test with a simple request to rule out local issues

2. Optimize large requests

   • Break large batch requests into smaller chunks
   • Use pagination for data-heavy queries
   • Consider using WebSocket connections for real-time data

3. Implement timeouts

   • Set appropriate timeout values in your client code (30-60 seconds)
   • Handle timeout errors gracefully with retries

4. Monitor service status

   • Check the Helius Status Page for network issues
   • Look for reports of high blockchain congestion

Gateway timeouts often indicate network congestion or complex operations. Consider breaking large requests into smaller parts.

Need More Help?

Contact Support

Get help from our team through Discord, chat, or email support.

Status Page

Check real-time service availability and performance information.