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"}}curl $RPC/$KEY \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
HTTP 429
Retry-After: 1
{"jsonrpc":"2.0","id":1,"error":{"code":429,
"message":"Request rate limit exceeded"}}curl $RPC/$KEY \
-H 'content-type: application/json' \
-d '[{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]},
{"jsonrpc":"2.0","id":2,"method":"trace_block","params":[]}]'
HTTP 200
[{"jsonrpc":"2.0","id":1,"result":"0x1237"},
{"jsonrpc":"2.0","id":2,"error":{"code":-32601,
"message":"The method trace_block 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.
| Case | HTTP | JSON-RPC error | What a client does |
|---|---|---|---|
| No key, or a key that does not exist or was revoked | 401 | -32600 “Invalid access key” | Check the key, or make a new one in the dashboard. |
| A body that is not JSON | 400 | -32700 “Parse error” | Fix the request. |
| A body that is not a call or a list of calls, or an empty list | 400 | -32600 “Invalid request” | Fix the request. |
| A body over 1 MB | 413 | -32600 “A request body holds up to 1 MB” | Send fewer calls in one request. |
| A batch of more than 100 calls | 400 | -32600 “A batch holds up to 100 calls and this one holds 120” | Split the batch. |
| A method that is not offered | 400 | -32601 “The method trace_block is not offered” | Send a method the endpoint answers. |
| A wrong parameter of an index call | 400 | -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 logs | 400 | -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 call | 400 | -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 keys | 429 | 429 “Request rate limit exceeded” | Wait the seconds in the Retry-After header, then send the request again. |
| The free month is used up | 403 | 403 “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 checked | 503 | None. The body is empty. | Send the request again in a few seconds. |
| A call ran past its time | 504 | -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 answer | 502 | -32603 “The node did not answer this call” | Send the request again. |
| An answer over 20 MB | 200 | -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 service | 500 | -32603 “Internal error” | Send the request again. If it keeps failing, write to developers@ |
What to retry
429: wait the seconds theRetry-Afterheader gives, then send the same request. A page in a browser can read the header.502,503and504: the call was not answered and does not count toward the month. Send it again after a moment. After a504, ask for less at once.- A batch answered
502or504: 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,401and413: 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.