> ## 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 and Streaming APIs.

Both the GoldRush Foundational API (REST) and the Streaming API (GraphQL/WebSocket) return 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>

## Streaming API (GraphQL/WebSocket) Errors

Authentication errors in the Streaming API are returned as GraphQL errors with specific extension codes:

| Code                | Description                                               |
| :------------------ | :-------------------------------------------------------- |
| `MISSING_TOKEN`     | No API key was provided in the `connection_init` payload. |
| `INVALID_TOKEN`     | The provided API key is malformed or invalid.             |
| `AUTH_SYSTEM_ERROR` | An internal server error occurred during authentication.  |

**Example error response:**

```json theme={null}
{
  "errors": [
    {
      "message": "Authentication required. Please provide a valid API key in the connection_init payload under 'GOLDRUSH_API_KEY' or 'Authorization' key.",
      "extensions": {
        "code": "MISSING_TOKEN"
      }
    }
  ]
}
```

<Note>
  Auth errors only surface when a subscription starts, **not** on WebSocket connect. The server always sends a `connection_ack` response regardless of whether the API key is valid. You will only discover an invalid key when you attempt to subscribe.
</Note>

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

### Streaming Reconnection

The GoldRush Client SDK manages WebSocket reconnection automatically. If you're using a custom [`graphql-ws`](https://github.com/enisdenjo/graphql-ws) client, configure the `shouldRetry` option:

```typescript theme={null}
import { createClient } from "graphql-ws";

const client = createClient({
  url: "wss://streaming.goldrushdata.com/graphql",
  connectionParams: {
    GOLDRUSH_API_KEY: "<GOLDRUSH_API_KEY>",
  },
  shouldRetry: () => true,
  retryAttempts: 5,
});
```

## 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](/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 or websocat">
    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'
    ```

    For the Streaming API, use [websocat](https://github.com/vi/websocat) - see the [Streaming API Authentication](/goldrush-streaming-api/authentication#use-websocat-for-manual-websocket-testing) guide for setup steps.
  </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="/goldrush-foundational-api/authentication">
    API key setup, authentication methods, and SDK usage.
  </Card>

  <Card title="Streaming API Auth" icon="signal-stream" href="/goldrush-streaming-api/authentication">
    WebSocket authentication and connection management.
  </Card>

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

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