Error Reference

When a request fails, the Ankr RPC gateway returns a standard JSON-RPC error object — a numeric code, a human-readable message, and a data.trace_id you can quote to support. HTTP requests also carry the matching HTTP status code. Codes in the -326xx range are returned by the Ankr gateway; errors from the blockchain node itself pass straight through to you.

How errors are returned

JSON-RPC (HTTP POST, batch, and WebSocket) — the response replaces result with an error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32055,
    "message": "No nodes available",
    "data": { "trace_id": "4b1f...e9c2" }
  }
}

Plain HTTP (request rejected before it reaches JSON-RPC handling — bad auth, rate limit, oversized body) — the gateway returns the HTTP status with a short text body:

message: API key not found, trace_id: 4b1f...e9c2

:::tip Always keep the trace_id Every gateway error carries a trace_id. Include it when you contact support and we can look up the exact request — no need to reproduce it. :::

Client-side vs server-side

Two kinds of error, and they need opposite responses:

• Client-side (HTTP 4xx) — something about the request, key, or plan needs to change. Retrying as-is won't help — fix the cause first.
• Server-side (HTTP 5xx) — a transient condition on our side or the upstream node. Safe to retry with backoff. See Retry strategies.

Standard JSON-RPC errors

These follow the JSON-RPC 2.0 spec.

Code	HTTP	Message	What it means / what to do
-32700	400	Parse error	The request body isn't valid JSON. Check serialization.
-32600	400	Invalid Request	The JSON isn't a valid JSON-RPC request object.
-32601	404	Method not found	The method doesn't exist or isn't enabled for this chain. Check the method name and the chain's API reference.
-32602	400	Invalid params	Wrong number or type of params. Check the method signature.
-32603	500	Internal error	Unexpected server-side error. Safe to retry.

Authentication & API-key errors

Returned when the key is missing, unknown, or not entitled. All are client-side — fix the key or your plan in the dashboard before retrying.

Code	HTTP	Message	What it means / what to do
-32049	401	API Key required	This endpoint needs a key. Use your Premium endpoint with the key in the path.
-32050	401	API key not found	The key doesn't exist. Check for typos or a deleted key.
-32051	403	API key disabled	The key was disabled in the dashboard. Re-enable it or use another.
-32060	403	API key expired	The key's validity period has ended.
-32052	403	API key is not allowed to access blockchain	This chain isn't enabled for the key. Add it in the project settings.
-32053	403	API key is not allowed to access method	The method isn't permitted for this key.
-32054	403	API key is not allowed to access from this IP	The request came from an IP outside the key's IP allowlist.
-32079	403	Origin not allowed	The request Origin isn't on the key's domain allowlist.
-32080	403	Contract address not allowed	The call targets a contract outside the key's smart-contract allowlist.

Feature & availability restrictions

The request is well-formed and authenticated, but the feature isn't available on this key, plan, or chain. Client-side.

Code	HTTP	Message	What it means / what to do
-32074	403	Blockchain disabled	This chain is temporarily disabled.
-32075	403	Method disabled	This method is disabled on the gateway.
-32093	403	Blockchain not supported	This chain isn't served. See supported chains.
-32083	403	Proxy is disabled	The endpoint is disabled.
-32078	403	Streaming not supported	A streaming request hit a non-streaming endpoint.
-32082	403	Event not supported	The WebSocket subscription event isn't supported here.
-32092	403	WebSocket is disabled	WebSocket isn't enabled for this key.

Rate-limit & connection-limit errors

You're sending more than your plan allows. Client-side — slow down, back off, or upgrade. See Avoid rate limiting.

Code	HTTP	Message	What it means / what to do
-32090	429	Too many requests	Request-rate limit exceeded. Back off and retry.
-32067	429	Max connections per blockchain reached	Too many concurrent connections to one chain.
-32068	429	Max connections per api key reached	Too many concurrent connections on the key.
-32069	429	Max connections per ip reached	Too many concurrent connections from one IP.
-32077	429	Max connections per tenant reached	Account-wide connection cap reached.
-32070	429	Max total connections reached	The gateway is at capacity. Retry with backoff.

Request-size errors

The request exceeds a size or range limit. Client-side — split it up.

Code	HTTP	Message	What it means / what to do
-32062	413	Request is too large	The request body exceeds the limit.
-32062	413	Block range is too large	An eth_getLogs/trace_* range is too wide. Split into smaller block ranges.
-32062	413	Batch size too large	Too many calls in one batch. Send fewer per batch.
-32081	413	WS message is too large. Please use RPC instead	A WebSocket payload is too big — use HTTP RPC.

Node-availability & upstream errors

Transient conditions reaching a healthy node. Server-side (5xx) — safe to retry with backoff.

Code	HTTP	Message	What it means / what to do
-32055	404	No nodes available	No healthy node could serve the request right now. Retry.
-32061	503	No archive nodes available	An archive-only query (historical state, trace_*) found no archive node available. Retry.
-32057	503	Node responded with non success status code	The upstream node returned an error status. Retry.
-32059	503	Failed to dial node	The gateway couldn't connect to a node. Retry.
-32056	500	Proxy error	A request couldn't be completed within the upstream deadline. Retry.
-32063	500	Node returned unexpected error	An unexpected upstream error. Retry.
-32064	503	Retry failed	The gateway retried across nodes and all attempts failed. Retry after a short pause.
-32071	504	Request timeout error	The request exceeded the time limit. Retry; if it's a heavy call, narrow it.
-32076	500	Invalid response	The node returned a malformed response. Retry.
-32065	500	Decompress response error	The gateway couldn't decompress the node response. Retry.

WebSocket node availability

No node currently supports the requested subscription. Server-side — retry, or fall back to HTTP polling.

Code	HTTP	Message
-32085	503	No alive WS nodes
-32086	503	No alive WS nodes supporting newHeads
-32087	503	No alive WS nodes supporting logs
-32088	503	No alive WS nodes supporting newPendingTransactions
-32089	503	No alive WS nodes supporting transactionReceipts

Internal & connection errors

Code	HTTP	Message	What it means / what to do
-32072	500	Failed to rebuild request	Internal error preparing the request. Retry.
-32073	500	Failed to rebuild response	Internal error preparing the response. Retry.
-32084	500	WS message IO error	A WebSocket read/write failed. Reconnect.
-32091	500	Failed to hijack connection	Internal connection-upgrade error. Reconnect.
-32100	400	Failed to write response	The response couldn't be written back. Retry.
-32099	499	Client disconnected	The client closed the connection before the response was sent — usually a client-side timeout that's too short.

Errors from the blockchain node

Codes outside the -326xx gateway range come straight from the node and mean your request reached a node and was executed. Common examples:

• 3 / "execution reverted" — the contract call reverted (a normal smart-contract outcome, not an Ankr error).
• -32000 — a node-level condition such as "header not found", a block/state that's been pruned, or a block that doesn't exist yet (a future block number).

For these, consult the node client's documentation for the chain. For history that's been pruned from a full node, use an archive-tier endpoint.

FAQ

What is the trace_id for?

Every gateway error includes a trace_id in error.data (JSON-RPC) or the text body (HTTP). Quote it to support and we can find the exact request without you reproducing it.

Which errors should I retry?

Server-side errors (HTTP 5xx: -32055, -32056, -32057, -32059, -32061, -32063, -32064, -32071, -32076, and the WS -3208x codes) are transient — retry with exponential backoff. Client-side errors (4xx: auth, access, rate-limit, size) need a fix first. See Retry strategies.

A -326xx code isn't in this list — what is it?

The -326xx range is reserved for the Ankr gateway and standard JSON-RPC. If the code is outside that range, it came from the blockchain node, not Ankr.

I keep getting 429 (-32090). How do I fix it?

You're over your plan's request rate. Add exponential backoff, batch where you can, or upgrade your plan. See Retry strategies and Pricing.