> ## 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

<AccordionGroup>
  <Accordion title="Why am I getting a 401 error?">
    ## What this means

    <Warning>**401 Unauthorized** - Your request lacks valid authentication credentials.</Warning>

    ## 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

    <Info>For detailed authentication setup, see our [Authentication](/api-reference/authentication) guide.</Info>
  </Accordion>

  <Accordion title="Why am I getting a 429 error?">
    ## What this means

    <Warning>**429 Too Many Requests** - You've exceeded your plan's rate limits.</Warning>

    ## 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](/billing/plans) for higher tiers

    <Tip>Rate limits reset every minute, so temporary throttling usually resolves quickly.</Tip>
  </Accordion>

  <Accordion title="Why am I getting a 500 error?">
    ## What this means

    <Warning>**500 Internal Server Error** - A server-side error occurred while processing your request.</Warning>

    ## 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.</Note>
  </Accordion>

  <Accordion title="Why am I getting a 503 error?">
    ## What this means

    <Warning>**503 Service Unavailable** - The server is temporarily overloaded or under maintenance.</Warning>

    ## 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.</Tip>
  </Accordion>

  <Accordion title="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.</Warning>

    ## 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.</Note>
  </Accordion>
</AccordionGroup>

## Need More Help?

<CardGroup cols={2}>
  <Card title="Contact Support" icon="headset" href="/support/contact-support">
    Get help from our team through Discord, chat, or email support.
  </Card>

  <Card title="Status Page" icon="wave-pulse" href="/support/status-page">
    Check real-time service availability and performance information.
  </Card>
</CardGroup>