Errors
A consistent envelope with stable, machine-readable codes.
Errors return the appropriate HTTP status and a JSON body with a stable code, a human-readable message, and the requestId for support.
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "This request costs 105 credits but your organization has 40.",
"requestId": "req_01HZ..."
}
}| Code | HTTP | Meaning |
|---|---|---|
| INVALID_API_KEY | 401 | Missing, malformed, invalid, or revoked API key. |
| INSUFFICIENT_CREDITS | 402 | Not enough credits to cover the request. |
| RATE_LIMITED | 429 | Too many requests for this key + endpoint in the window. |
| INVALID_CHAIN | 400 | Unknown chain slug (also surfaced per-chain in errors[]). |
| INVALID_ADDRESS | 400 | The address could not be parsed. |
| UPSTREAM_PROVIDER_ERROR | 502 | A data provider failed (also surfaced per-chain in errors[]). |
| NOT_IMPLEMENTED | 501 | Endpoint is not available yet (Gas / Quotes). |
| INTERNAL_ERROR | 500 | Unexpected server error. |
Note: INVALID_CHAIN and UPSTREAM_PROVIDER_ERROR can also appear per-chain inside the errors[] array of an otherwise successful balances response.