Skip to main content

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​

CodeWhen
MISSING_API_KEYNo x-api-key header
INVALID_API_KEYUnknown or revoked key
EXPIRED_API_KEYValid key, past its expiry — rotate it
MISSING_TOKENDashboard route called without a session token
INVALID_TOKENSession token rejected

403 — authenticated, but not yours to read​

CodeWhen
PUBLIC_ACCESS_DISABLEDThe environment is not handing out public access
PROTOCOL_NOT_PUBLICThat protocol has not enabled public exploration
COMPONENT_DISABLEDThe data behind this resource is off for that protocol
WALLET_SCOPE_UNAVAILABLEWallet-scoped resource requested across protocols
TENANT_ADMIN_REQUIREDKey management on a protocol you do not administer
SUPERADMIN_REQUIREDPlatform administration route
EMAIL_NOT_VERIFIEDIssuing a key before verifying the account's e-mail
CATALOG_MISMATCHThe 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​

StatusCodeMeaning
402INSUFFICIENT_CREDITSBalance exhausted; details carries the top-up link
404NOT_FOUNDAlso the answer for a resource that exists but is not yours — the API does not confirm existence it will not serve
409KEY_LIMIT_REACHEDThe account or protocol is at its key ceiling
422VALIDATION_FAILEDWell-formed, semantically rejected; details is field-level
429RATE_LIMITEDSent with Retry-After and the RateLimit-* headers
503SETTINGS_UNAVAILABLEA setting could not be read. Distinct from any answer it could have given
503WALLET_UNAVAILABLEBilling could not be reached
500INTERNALOur 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.