Skip to main content
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.
CodeNameCommon Cause
400Bad RequestMalformed parameters, invalid address format
401UnauthorizedMissing or incorrect API key
402Payment RequiredCredits exhausted — enable Flex Credits or upgrade tier
403ForbiddenAPI key is valid but not authorized for the resource
404Not FoundUnsupported chain, invalid endpoint
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side failure
503Service UnavailableMaintenance or outage
Example error responses: 
{
  "error": true,
  "error_message": "No valid API key was provided.",
  "error_code": "401"
}

​
Streaming API (GraphQL/WebSocket) Errors

Authentication errors in the Streaming API are returned as GraphQL errors with specific extension codes:
CodeDescription
MISSING_TOKENNo API key was provided in the connection_init payload.
INVALID_TOKENThe provided API key is malformed or invalid.
AUTH_SYSTEM_ERRORAn internal server error occurred during authentication.
Example error response: 
{
  "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"
      }
    }
  ]
}
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.

​
Rate Limits

The Foundational API enforces rate limits based on your plan tier:
PlanRate LimitAPI Credits
14-day Free Trial4 RPS25,000
Vibe Coding ($10/mo)4 RPS10,000
Professional ($250/mo)50 RPS300,000
Inner CircleCustom (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. 
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");
}

​
SDK Built-in Retries

The GoldRush TypeScript 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 client, configure the shouldRetry option: 
import { createClient } from "graphql-ws";

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

​
Debugging Tips

GoldRush API keys follow the pattern cqt_wF... or cqt_rQ... (26 base58 characters after the prefix). Double-check for trailing whitespace or truncation.
A 404 error often means the chain is unsupported. See Supported Chains for the full list.
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.
Isolate issues from your application code by testing directly:
# Foundational API
curl -X GET https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
     -u YOUR_API_KEY_HERE: \
     -H 'Content-Type: application/json'
For the Streaming API, use websocat — see the Streaming API Authentication guide for setup steps.
Track your API credit consumption on the GoldRush Platform dashboard to avoid unexpected 402 errors.
If you’re consistently hitting 500 or 503 errors, reach out to [email protected] with your API key prefix, the endpoint, and timestamps of the failures.

​
Quick Reference

Foundational API Auth

API key setup, authentication methods, and SDK usage.

Streaming API Auth

WebSocket authentication and connection management.

FAQ

Common questions about plans, rate limits, and features.

Supported Chains

Full list of supported blockchains and endpoints.