Errors
One shape for every failure, with a stable code to branch on.
Every non-2xx response is RFC 9457
application/problem+json:
{
"type": "https://docs.avee.tech/errors/chain_not_found",
"title": "unknown chain",
"status": 404,
"code": "chain_not_found",
"detail": "no chain is indexed under solanaa; read GET /api/v1/chains for the current roster",
"param": "chain",
"request_id": "4f2f55b661800b572544525f0ec25ec5"
}Branch on code, never on detail. The code is part of the contract; the wording is for a person
reading a log.
| Code | Status | Meaning | What to do |
|---|---|---|---|
invalid_param | 400 | A parameter or body failed validation. | Read param. |
key_in_query | 400 | A key was sent in the query string. | Send it in the X-API-Key header. |
invalid_api_key | 401 | The key sent is unknown or revoked. | Fix the key, or send none. |
plan_required | 403 | The operation needs a higher plan. | Call an operation your plan includes. |
chain_not_found | 404 | No chain under that slug or id. | Read GET /chains. |
not_found | 404 | No pair, token or record matches. | Check the address and the chain. |
rate_limited | 429 | The budget is spent. | Wait Retry-After seconds. |
internal | 500 | Unexpected server error. | Quote request_id. |
upstream_unavailable | 503 | A data service is down. | Retry; nothing was lost. |
upstream_timeout | 504 | A data service did not answer in time. | Retry. |
The set is closed within v1 and a code never changes meaning. type is a link to this page.
request_id
Every response carries X-Request-Id, and every error repeats it in the body. Log it: it turns a
support question into a single lookup. Send your own X-Request-Id (letters, digits, - and _, up
to 64 characters) and it is echoed back instead of a new one.