Skip to Content
Blockhash Docs
Data API

Errors

The one error envelope, its headers, and what each status means.

The envelope

Every answer that is not a success is one envelope. A request for a malformed address answers this, with status 400:

curl -s https://api.blockhash.xyz/v1/tokens/0x123/candles
{"error":"bad address","code":"bad-address","retryable":false}
FieldWhat it is
errorA sentence for people. Show it, and do not parse it.
codeA stable code. Branch on it. A code keeps its meaning for good, and a new rule takes a new code. The ErrorCode schema in the OpenAPI document lists every one.
retryableWhether the same request, sent again unchanged after Retry-After, may succeed.
retryAfterSecondsThe seconds of the Retry-After header, where the answer carries one.
detailWhat a refusal names, by code.

A route's own fields stay beside these: a 429 from the rate buckets names its bucket. An answer that is not JSON, such as an image or the event stream, keeps its own body.

Headers

HeaderOnWhat it is
Retry-AfterEvery 429 and every 503Seconds to wait before sending the request again.
X-Request-IdEvery answerYour own X-Request-Id echoed, where it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one made for the request.
RateLimit-PolicyEvery answerThe rate bucket nearest its end: "<bucket>";q=<burst>;w=<seconds to refill from empty>.
RateLimitEvery answerThat bucket now: "<bucket>";r=<requests left at once>;t=<seconds until full>.

Name the answer's X-Request-Id when you write to developers@blockhash.xyz.

Statuses

StatusCodesWhat to do
400A request that is wrong, its code saying what: bad-address, bad-tx-hash, bad-pool, bad-wallet, bad-token, bad-timeframe, bad-filter, bad-cursor, bad-query, bad-request.Fix the request.
403key-server-only: a key sent with a browser's Origin.Send the key from your server.
404not-found, unknown-token, unknown-pool or transaction-not-found.Check the path and the address.
429rate-limited, naming its bucket, or a route's own allowance; too-many-streams.Wait the Retry-After seconds: Rate limits.
500internal-error.Retry.
503A store did not answer (store-unavailable, store-busy, unavailable). keys-unavailable: the server could not check the key the request carries.Retry with backoff after Retry-After.

A transaction in a block not indexed yet is no error: its flow answers source: node with the head and value alone, so ask again shortly.

On this page