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.

Failed requests are free. No API credits are deducted for any response outside the 2xx range, whatever the cause. A 429, a 501, a 556 and a 500 all cost you nothing, so a retry is never a billing risk.

Retries do still count against your rate limit, which is why the guidance below is about backing off correctly rather than about cost.

Standard and GoldRush-specific codes

Not every code this API returns is a registered HTTP status code. It is worth knowing which is which, because off-the-shelf HTTP clients, proxies and monitoring tools only understand the registered ones and will usually flatten the rest into a generic “5xx”.

Standard HTTP codes

400 401 402 403 404 406 410 416 429 500 501 503 504 507

Registered status codes. Several carry a GoldRush-specific meaning, noted in the table below.

GoldRush-specific codes

452 551 552 554 556 557 558 561 562 563 565 567 570

Not registered HTTP status codes. Specific to the GoldRush API. Match on the exact number, not on the 5xx class.

The error response body

Every error the API itself generates uses the same envelope as a successful response, with data set to null:

{
  "data": null,
  "error": true,
  "error_message": "This chain does not currently support flag: with-state.",
  "error_code": 501
}

Three things to note:

• error_code is a JSON number, not a string. Compare it with 501, not "501".
• error_code always equals the HTTP status code, so you can branch on either one.
• error_message carries the specific reason. Two requests can share a status code and mean entirely different things, so log the message as well as the code.

The one exception is a bare 500, which is returned with an empty body. Treat a response that has a 5xx status and no parseable JSON as a 500.

A request with no Authorization header at all is rejected by the edge proxy, not by the API, and returns an HTML body rather than JSON:

<html><head><title>401 Authorization Required</title></head> ...

A missing or malformed key sent with the request returns the normal JSON 401. If your client parses every response body as JSON, guard this one case, or check the Content-Type header before parsing.

Standard HTTP status codes

These are all registered HTTP status codes. Where our meaning is narrower or more specific than the generic one, it is spelled out here.

Code	Name	What it means at GoldRush
400	Bad Request	Malformed parameters, invalid address format
401	Unauthorized	Missing or incorrect API key
402	Payment Required	Three distinct causes, told apart by error_message: credit limit exceeded, a paywalled feature on your tier, or a paused subscription on a production key
403	Forbidden	API key is valid but not authorized for the resource
404	Not Found	The endpoint path does not exist, or the specific record (transaction hash, block) was not found. Also returned when a requested block height has not been reached yet on that chain
406	Not Acceptable	The request would predictably time out with these parameters, so it was not attempted. Reduce the date range or page size and retry
410	Gone	The endpoint or the chain has been sunsetted. Stop calling it and remove any scheduled jobs that do
416	Range Not Satisfiable	A query transform supplied with the request failed to parse
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	An unclassified server-side failure. Unlike every other code on this page, a 500 has no JSON body
501	Not Implemented	The chain or endpoint does not support what you asked for. This is the most commonly misread code we return, so it has its own section below
503	Service Unavailable	The chain is under maintenance, or a backend queue is full
504	Gateway Timeout	A database query exceeded its statement timeout. Narrow the query and retry
507	Insufficient Storage	The response was too large to buffer. Reduce page-size and retry

501 is a capability answer, not an outage

A 501 means your request was well-formed and your key was fine, but the chain or endpoint cannot serve that particular thing. It is a stable answer rather than a transient one, so retrying it unchanged will not succeed until that support actually ships. It is returned in three situations:

• An unsupported chain. Note that an unrecognized chain name returns 501, not 404:

  { "data": null, "error": true, "error_message": "Chain nosuchchain-mainnet not supported.", "error_code": 501 }
  

• A feature flag the chain does not support. Flags such as with-state and with-input-data are only available on chains with the underlying data. The flag is valid, the chain just cannot serve it:

  { "data": null, "error": true, "error_message": "This chain does not currently support flag: with-state.", "error_code": 501 }
  

  Rather than discovering this by trial, read the capability flags on /v1/chains/, such as is_internal_tx_supported and is_input_data_supported, and skip the call when the flag is false.

• An endpoint restricted to certain chains, for example an EVM-only endpoint called on a non-EVM chain.

The gate runs before the identifier is looked up, so a transaction hash that does not exist returns 404 on a chain that supports the flag and 501 on a chain that does not. That makes a throwaway hash a cheap way to test chain support.

GoldRush-specific status codes

The codes in this section are not registered HTTP status codes. They are specific to the GoldRush API.

They exist so that different backend conditions stay distinguishable instead of collapsing into one generic 500, which is what makes a useful retry policy possible at all. The tradeoff is that generic HTTP tooling does not know them: most clients, proxies and dashboards will report them only as “a 5xx”. Match on the exact number, and if you alert on error classes, give at least 556 and 565 their own treatment.

All of these carry the normal JSON error body described above.

Code	error_message	What happened	What to do
452	Please un-stealth your User-Agent	Your client sent a browser User-Agent but is not a browser	Do not retry. Set an honest User-Agent that identifies your application, then retry once
551	Worker thread failed to respond in time	A worker did not finish within its deadline	Retry with exponential backoff. If it repeats on the same parameters, the request is probably too broad: narrow the date range or page size
552	Connection to web3 provider failed	We could not reach the chain’s node for a live call	Retry with exponential backoff, up to 3 to 5 attempts
554	Timed out while waiting to acquire a database connection	All pooled database connections were busy	Retry with exponential backoff. Transient and usually clears within seconds
556	Too many concurrent database requests	Deliberate load shedding. The query was refused on purpose to protect a saturated backend	Retry with exponential backoff, and lower your concurrency. Do not retry tightly, see the note below
557	Database replica cancelled query to retain sync with primary	A read replica cancelled the query to stay in sync	Retry once, immediately. This one is usually gone on the next attempt
558	Database unexpectedly closed connection	The connection dropped mid-query	Retry with exponential backoff, up to 3 attempts
561	Could not acquire NFT metadata scraper from pool	The NFT metadata scraping pool was exhausted	Retry with exponential backoff. Consider spacing out bulk NFT metadata jobs
562	Failed to connect to upstream third-party service	A third-party data provider we depend on was unreachable	Retry with exponential backoff. Recovery depends on a third party, so allow a longer ceiling, 30 to 60 seconds
563	Connection to upstream third-party service timed out	A third-party data provider did not answer in time	Retry with exponential backoff, same longer ceiling as 562
565	Unable to find referenced <record> in database; DB has fallen behind web3 source	The record exists on chain but our indexed copy has not caught up. Most often a transaction requested within seconds of being mined	Wait at least 10 seconds, then retry once. See the note below, do not retry immediately
567	Chain dataset is currently unavailable	The dataset for that chain is temporarily not readable	Retry after 30 seconds or more. If it persists past a few minutes, treat that chain as down and fail over
570	Contract execution error during web3 call	The contract call reverted on chain	Do not retry. This is a correct answer about the contract, not a failure on our side. Check your call arguments

556 is the one to watch. It means the request was refused on purpose while the backend was under load, not that anything is broken. A burst of 556 is the correct signal to back off; clients that retry it aggressively make the condition worse and last longer.

565 is short-lived by design. The response is cached for only 10 seconds, because the usual cause is that indexing is a few seconds behind the chain tip. Waiting 10 to 15 seconds and retrying once resolves most occurrences. If a 565 for the same record persists for minutes, raise it on the support page.

What to do with every code

Sorted by what the right response actually is, rather than by number.

Retry with exponential backoff

429, 500, 503, 504, 551, 552, 554, 556, 557, 558, 561, 562, 563, 565, 567

These are transient. The same request may well succeed later. Use the loop in Retry Strategies below, with these adjustments:

• 557: retry once immediately before backing off. It usually clears on the next attempt.
• 565: wait at least 10 seconds before the first retry.
• 562 and 563: recovery depends on a third party, so allow a ceiling of 30 to 60 seconds rather than a few seconds.
• 429: back off until your request rate is under the limit for your plan. More attempts will not help.

Change the request, then retry

406, 507

The request as sent will keep failing, but a narrower one will succeed. Reduce page-size, shorten the date range, or split the query, then send it again.

Fix something, then retry once

400 fix the parameters. 401 fix the API key. 402 check error_message to see which of the three causes applies, then raise your spending limit, upgrade your plan, or resume your subscription. 452 send an honest User-Agent.

Do not retry

403, 410, 416, 501, 570

These are stable answers, not failures in progress. Retrying returns exactly the same thing. 410 means the endpoint or chain is gone for good, so remove the call and any scheduled job that makes it. 501 means the capability does not exist on that chain, so check /v1/chains/ and skip it. 570 means the contract reverted, which is a real answer about the contract.

None of this costs credits. Error responses are not billed, so the cost of a retry is only the rate limit slot it consumes and the latency it adds. Optimize your retry policy for recovery time and for not amplifying an incident, not for spend.

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

Retry on the transient set only, and use exponential backoff with random jitter so that many clients recovering from the same incident do not retry in lockstep.

A retry loop written against 429, 500 and 503 alone will miss most of what the API actually returns under load, because the specific codes above are used in preference to a generic 500. Include them explicitly.

TypeScript

// Transient: a later attempt may succeed with the same request.
const RETRYABLE = new Set([
  429, 500, 503, 504,
  551, 552, 554, 556, 557, 558, 561, 562, 563, 565, 567,
]);

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 (RETRYABLE.has(response.status)) {
      // 565 means indexing is a few seconds behind the chain tip,
      // so give it a floor of 10s rather than retrying immediately.
      const baseDelay =
        response.status === 565
          ? 10_000
          : 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");
}

Never put 403, 410, 416, 501 or 570 in a backoff loop. They are stable answers about the request, the chain or the contract, so every attempt returns the same thing while still consuming a rate limit slot. See What to do with every code for the codes that are worth one retry after you fix something.

SDK Built-in Retries

The GoldRush TypeScript Client SDK handles retries and rate limiting automatically - no manual retry logic needed when using the SDK.

Debugging Tips

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.

Check supported chains

An unsupported or misspelled chain returns 501, not 404, with "Chain <name> not supported." in error_message. A 404 on a chain-scoped path usually means the record was not found, not that the chain is wrong. See Supported Chains for the full list.

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. This matters most for 402 and 501, where one status code covers several unrelated causes that only the message distinguishes.

Test with curl

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 <GOLDRUSH_API_KEY>: \
     -H 'Content-Type: application/json'

Monitor credit usage

Track your API credit consumption on the GoldRush Platform dashboard to avoid unexpected 402 errors.

Contact support for persistent server-side errors

If you’re consistently hitting 500, 503, or any of the GoldRush-specific 5xx codes after backing off, open a ticket on the GoldRush support page with your API key prefix, the endpoint, the exact error_code and error_message, and timestamps of the failures.

The support form asks for the endpoint and chain directly, so filing there routes the issue faster than describing it in free text.

Include the exact code. 556 and 565 in particular point at very different causes from a generic 500, and quoting the number shortens the diagnosis considerably.

Quick Reference

Foundational API Auth

API key setup, authentication methods, and SDK usage.

FAQ

Common questions about plans, rate limits, and features.

Supported Chains

Full list of supported blockchains and endpoints.