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

# Error Handling & Troubleshooting

> Comprehensive guide to error codes, rate limits, retry strategies, and debugging tips for the GoldRush Foundational API.

The GoldRush Foundational API (REST) returns structured errors when something goes wrong. This page is the single reference for understanding error codes, handling rate limits, implementing retries, and debugging common issues.

## Foundational API (REST) Errors

The Foundational API returns standard HTTP status codes along with a JSON error body.

| Code  | Name                  | Common Cause                                            |
| :---- | :-------------------- | :------------------------------------------------------ |
| `400` | Bad Request           | Malformed parameters, invalid address format            |
| `401` | Unauthorized          | Missing or incorrect API key                            |
| `402` | Payment Required      | Credits exhausted - enable Flex Credits or upgrade tier |
| `403` | Forbidden             | API key is valid but not authorized for the resource    |
| `404` | Not Found             | Unsupported chain, invalid endpoint                     |
| `429` | Too Many Requests     | Rate limit exceeded                                     |
| `500` | Internal Server Error | Server-side failure                                     |
| `503` | Service Unavailable   | Maintenance or outage                                   |

**Example error responses:**

<CodeGroup>
  ```json 401 Unauthorized theme={null}
  {
    "error": true,
    "error_message": "No valid API key was provided.",
    "error_code": "401"
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "error": true,
    "error_message": "You are being rate-limited. Please reduce request frequency.",
    "error_code": "429"
  }
  ```
</CodeGroup>

## Rate Limits

The Foundational API enforces rate limits based on your plan tier:

| Plan                    | Rate Limit              | API Credits |
| :---------------------- | :---------------------- | :---------- |
| 14-day Free Trial       | 4 RPS                   | 25,000      |
| Vibe Coding (\$10/mo)   | 4 RPS                   | 10,000      |
| Professional (\$250/mo) | 50 RPS                  | 300,000     |
| Inner Circle            | Custom (up to 100+ RPS) | Custom SLA  |

Rate limits are enforced **per API key and IP address**. When you exceed your limit, you'll receive a `429 Too Many Requests` response. Back off and retry using the strategies below.

## Retry Strategies

### Exponential Backoff with Jitter

For transient errors (`429`, `500`, `503`), implement exponential backoff with random jitter to avoid thundering herd problems.

<CodeGroup>
  ```typescript TypeScript theme={null}
  async function fetchWithRetry(
    url: string,
    options: RequestInit,
    maxRetries = 5
  ): Promise<Response> {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url, options);

      if (response.ok) return response;

      if ([429, 500, 503].includes(response.status)) {
        const baseDelay = Math.pow(2, attempt) * 1000;
        const jitter = Math.random() * 1000;
        await new Promise((r) => setTimeout(r, baseDelay + jitter));
        continue;
      }

      throw new Error(`Request failed: ${response.status}`);
    }

    throw new Error("Max retries exceeded");
  }
  ```

  ```python Python theme={null}
  import time
  import random
  import requests

  def fetch_with_retry(url, headers, max_retries=5):
      for attempt in range(max_retries):
          response = requests.get(url, headers=headers)

          if response.ok:
              return response

          if response.status_code in (429, 500, 503):
              base_delay = (2 ** attempt)
              jitter = random.uniform(0, 1)
              time.sleep(base_delay + jitter)
              continue

          response.raise_for_status()

      raise Exception("Max retries exceeded")
  ```
</CodeGroup>

### SDK Built-in Retries

The [GoldRush TypeScript Client SDK](https://www.npmjs.com/package/@covalenthq/client-sdk) handles retries and rate limiting automatically - no manual retry logic needed when using the SDK.

## Debugging Tips

<AccordionGroup>
  <Accordion title="Verify your API key format">
    GoldRush API keys follow the pattern `cqt_wF...` or `cqt_rQ...` (26 base58 characters after the prefix). Double-check for trailing whitespace or truncation.
  </Accordion>

  <Accordion title="Check supported chains">
    A `404` error often means the chain is unsupported. See [Supported Chains](/docs/chains/overview) for the full list.
  </Accordion>

  <Accordion title="Inspect the full error body">
    Don't rely on the HTTP status code alone. The JSON response body contains an `error_message` field with specific details about what went wrong.
  </Accordion>

  <Accordion title="Test with curl">
    Isolate issues from your application code by testing directly:

    ```bash theme={null}
    # Foundational API
    curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
         -u <GOLDRUSH_API_KEY>: \
         -H 'Content-Type: application/json'
    ```
  </Accordion>

  <Accordion title="Monitor credit usage">
    Track your API credit consumption on the [GoldRush Platform dashboard](https://goldrush.dev/platform) to avoid unexpected `402` errors.
  </Accordion>

  <Accordion title="Contact support for persistent 500/503 errors">
    If you're consistently hitting `500` or `503` errors, reach out to [support@covalenthq.com](mailto:support@covalenthq.com) with your API key prefix, the endpoint, and timestamps of the failures.
  </Accordion>
</AccordionGroup>

## Quick Reference

<CardGroup cols={2}>
  <Card title="Foundational API Auth" icon="key" href="/docs/goldrush-foundational-api/authentication">
    API key setup, authentication methods, and SDK usage.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/docs/faq">
    Common questions about plans, rate limits, and features.
  </Card>

  <Card title="Supported Chains" icon="link" href="/docs/chains/overview">
    Full list of supported blockchains and endpoints.
  </Card>
</CardGroup>