Errors
Every error is the same envelope, whatever produced it:
{
"error": {
"code": "MISSING_REQUIRED_FILTER",
"message": "protocol is required on this resource",
"details": { "missing": ["protocol"] }
}
}
code is the contract — branch on it. message is prose for a human and may be reworded at any time. details is present only when there is something structured to say.
info
A code may be added in a minor release, but is never renamed or removed without a new API version. Treat an unrecognised code as a generic failure of its HTTP status class.
401 — no usable credential
| Code | When |
|---|---|
MISSING_API_KEY | No x-api-key header |
INVALID_API_KEY | Unknown or revoked key |
EXPIRED_API_KEY | Valid key, past its expiry — rotate it |
MISSING_TOKEN | Dashboard route called without a session token |
INVALID_TOKEN | Session token rejected |
403 — authenticated, but not yours to read
| Code | When |
|---|---|
PUBLIC_ACCESS_DISABLED | The environment is not handing out public access |
PROTOCOL_NOT_PUBLIC | That protocol has not enabled public exploration |
COMPONENT_DISABLED | The data behind this resource is off for that protocol |
WALLET_SCOPE_UNAVAILABLE | Wallet-scoped resource requested across protocols |
TENANT_ADMIN_REQUIRED | Key management on a protocol you do not administer |
SUPERADMIN_REQUIRED | Platform administration route |
EMAIL_NOT_VERIFIED | Issuing a key before verifying the account's e-mail |
CATALOG_MISMATCH | The service's visibility catalog disagrees with the stored one. Always a denial — never a silent grant |
400 — malformed request
MISSING_REQUIRED_FILTER · INVALID_SORT · INVALID_CURSOR · WINDOW_TOO_WIDE · INVALID_PARAMETER
See Conventions for what each of these guards.
The rest
| Status | Code | Meaning |
|---|---|---|
| 402 | INSUFFICIENT_CREDITS | Balance exhausted; details carries the top-up link |
| 404 | NOT_FOUND | Also the answer for a resource that exists but is not yours — the API does not confirm existence it will not serve |
| 409 | KEY_LIMIT_REACHED | The account or protocol is at its key ceiling |
| 422 | VALIDATION_FAILED | Well-formed, semantically rejected; details is field-level |
| 429 | RATE_LIMITED | Sent with Retry-After and the RateLimit-* headers |
| 503 | SETTINGS_UNAVAILABLE | A setting could not be read. Distinct from any answer it could have given |
| 503 | WALLET_UNAVAILABLE | Billing could not be reached |
| 500 | INTERNAL | Our fault. The cause is logged with the X-Request-Id you were given |
Retrying
429 and 503 are the retryable ones: honour Retry-After when it is present, otherwise back off exponentially. A 4xx other than 429 will fail identically however many times it is sent.