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}| Field | What it is |
|---|---|
error | A sentence for people. Show it, and do not parse it. |
code | A 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. |
retryable | Whether the same request, sent again unchanged after Retry-After, may succeed. |
retryAfterSeconds | The seconds of the Retry-After header, where the answer carries one. |
detail | What 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
| Header | On | What it is |
|---|---|---|
Retry-After | Every 429 and every 503 | Seconds to wait before sending the request again. |
X-Request-Id | Every answer | Your 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-Policy | Every answer | The rate bucket nearest its end: "<bucket>";q=<burst>;w=<seconds to refill from empty>. |
RateLimit | Every answer | That 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
| Status | Codes | What to do |
|---|---|---|
400 | A 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. |
403 | key-server-only: a key sent with a browser's Origin. | Send the key from your server. |
404 | not-found, unknown-token, unknown-pool or transaction-not-found. | Check the path and the address. |
429 | rate-limited, naming its bucket, or a route's own allowance; too-many-streams. | Wait the Retry-After seconds: Rate limits. |
500 | internal-error. | Retry. |
503 | A 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.