Skip to content
Sign inJoin the waitlist

Errors

The HTTP statuses and JSON-RPC errors the endpoint answers with, and what a client does about each.

How an error is answered

An error is a JSON-RPC error: a code and a message, under the id of the call it answers.

A request of one call is also answered with the HTTP status the table gives.

A batch is answered 200, and each call in it has its own result or its own error. Where calls of the batch went to the node or the index and none of them was answered, the status is 502, or 504 if one ran past its time.

A refusal of the whole request answers once, for all of it: the key, the body, the size of the batch, the speed and the month. Its id can be null.

The messages are written to be read. Match on the status and the code, not on the words.

curl $RPC/$KEY \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceTransaction","params":[]}'
HTTP 400
{"jsonrpc":"2.0","id":1,"error":{"code":-32601,
  "message":"The method debug_traceTransaction is not offered"}}

Every error

The status is the one a request of a single call is answered with.

A message that names a number or a method names the request’s own: the ones here are examples.

CaseHTTPJSON-RPC errorWhat a client does
No key, or a key that does not exist or was revoked401-32600 “Invalid access key”Check the key, or make a new one in the dashboard.
A body that is not JSON400-32700 “Parse error”Fix the request.
A body that is not a call or a list of calls, or an empty list400-32600 “Invalid request”Fix the request.
A body over 1 MB413-32600 “A request body holds up to 1 MB”Send fewer calls in one request.
A batch of more than 100 calls400-32600 “A batch holds up to 100 calls and this one holds 120”Split the batch.
A method that is not offered400-32601 “The method trace_block is not offered”Send a method the endpoint answers.
A wrong parameter of an index call400-32602 “order is "asc" or "desc"”Fix the parameter the message names.
A log read over 10,000 blocks, or one that holds more than 10,000 logs400-32602 “fromBlock and toBlock are 25,000 blocks apart: eth_getLogs reads up to 10,000 blocks a call”Narrow fromBlock and toBlock.
An index read too wide to answer in one call400-32602 “The request is too wide to answer in one call: narrow fromBlock and toBlock, or name the tokens in contractAddresses”Narrow the call as the message says.
Over the account’s speed, or over what the endpoint carries for all keys429429 “Request rate limit exceeded”Wait the seconds in the Retry-After header, then send the request again.
The free month is used up403403 “Monthly capacity limit exceeded”Wait for the next UTC month, or ask about a paid plan.
The node is behind the chain, or keys cannot be checked503None. The body is empty.Send the request again in a few seconds.
A call ran past its time504-32000 “The call ran past its time of 10 seconds”Ask for less at once, then send it again.
The node or the index did not answer502-32603 “The node did not answer this call”Send the request again.
An answer over 20 MB200-32000 “The answer is over 20 MB, the most one request is answered: ask for less at once (…)”Ask for less at once: a narrower range of blocks, fewer calls in a batch.
A fault in the service500-32603 “Internal error”Send the request again. If it keeps failing, write to developers@blockhash.xyz.

What to retry

  • 429: wait the seconds the Retry-After header gives, then send the same request. A page in a browser can read the header.
  • 502, 503 and 504: the call was not answered and does not count toward the month. Send it again after a moment. After a 504, ask for less at once.
  • A batch answered 502 or 504: none of its calls that were sent on was answered. Send the batch again.
  • 403: the month’s units are used up. The same request is refused until the next UTC month begins.
  • 400, 401 and 413: the request itself is wrong. Sent again unchanged, it gets the same answer.

The speeds and sizes behind these are on Limits and pricing. To ask about anything else, write to developers@blockhash.xyz.

Errors from the node

An error the node itself gives for a call is passed on as the node wrote it: a contract that reverted, a transaction the sequencer turned down.

It is answered 200, as a JSON-RPC error under the call’s id, and the call counts toward the month as it would with a result.

The one error of the node’s that does not count is -32601: a method the node does not have is a method that is not offered.

Where the node’s own code says the request was wrong (-32600, -32601, -32602 or -32700), the status is 400.

A read of state at a block the node no longer keeps comes back this way, with a sentence added that names blockhash_getTokenBalances.