> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes FAQ

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

> [accordion] Why am I getting a 401 error?
>
> ## What this means
>
> > [!WARNING]
> >
> > **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](https://dashboard.helius.dev/) for IP restrictions
>
>    * Ensure your domain is allowlisted if using browser requests
>
> > [!NOTE]
> >
> > For detailed authentication setup, see our [Authentication](https://www.helius.dev/docs/api-reference/authentication.md) guide.

> [accordion] Why am I getting a 429 error?
>
> ## What this means
>
> > [!WARNING]
> >
> > **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](https://dashboard.helius.dev/usage)
>    * 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](https://www.helius.dev/docs/billing/plans.md) for higher tiers
>
> > [!TIP]
> >
> > Rate limits reset every minute, so temporary throttling usually resolves quickly.

> [accordion] Why am I getting a 500 error?
>
> ## What this means
>
> > [!WARNING]
> >
> > **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](https://helius.statuspage.io/) 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
>
> > [!NOTE]
> >
> > Server errors are typically temporary and usually resolve automatically.

> [accordion] Why am I getting a 503 error?
>
> ## What this means
>
> > [!WARNING]
> >
> > **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](https://helius.statuspage.io/) 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
>
> > [!TIP]
> >
> > 503 errors are designed to be temporary - the service automatically recovers as server load decreases.

> [accordion] Why am I getting a 504 error?
>
> ## What this means
>
> > [!WARNING]
> >
> > **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](https://helius.statuspage.io/) for network issues
>
>    * Look for reports of high blockchain congestion
>
> > [!NOTE]
> >
> > Gateway timeouts often indicate network congestion or complex operations. Consider breaking large requests into smaller parts.

## Need More Help?

> [card] [Contact Support](https://www.helius.dev/docs/support/contact-support)
>
> Get help from our team through Discord, chat, or email support.

> [card] [Status Page](https://www.helius.dev/docs/support/status-page)
>
> Check real-time service availability and performance information.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.