Errors¶
Every /v1 error has the same shape, including the ones produced by credential
verification:
codeis the closed vocabulary your client should branch on.messageis for a human reading a log — it is not stable across versions.detailsis diagnostic, not part of the contract.request_idmatches theX-Request-Idresponse header; include it if you write to support.
code vocabulary¶
error.code |
HTTP | When |
|---|---|---|
invalid_request |
400 | The request does not match the expected schema |
unauthorized |
401 | Unknown, malformed, revoked, or expired key — same response for all four |
forbidden |
403 | A scope is missing (details.missing names it), or your tenant holds no licence in force — none, suspended, revoked or expired (details.code is LICENCE_INACTIVE and details.licence says which). A new token will not fix the second: renew the licence in the console. Also details.code MODULE_NOT_ENTITLED when the credential carries the scope but the tenant has not active its module (details.scopes, details.modules, and details.frameworks for a compliance framework in the plan but not activated); a new key does not help. And details.code IP_NOT_ALLOWED when the tenant has an IP allowlist and the request comes from an address outside it; the tenant's administrator adds the address. And details.code MFA_ENROLLMENT_REQUIRED for an OAuth access token (CLI, MCP client) whose account has not enrolled the second factor the tenant requires; enrol one in the console and sign in again. On a write (alerts:write), also details.code ROLE_NOT_PERMITTED (the role of the user who created the key may not make this change) or WRITE_ACTOR_UNRESOLVED (that user is gone, suspended or no longer reaches the tenant), and LICENCE_INACTIVE while the licence is in its grace period. And details.code PLAN_WITHOUT_API (with details.deniedReason plan_without_api) when your tenant's plan does not include API access, which starts at Comply, except AI Governance (also during a trial); a new key or token does not change this; API access is included from Comply, except AI Governance, and the plan can be changed in the console |
not_found |
404 | The resource doesn't exist, or the path doesn't exist |
method_not_allowed |
405 | A method the path does not serve (every path serves GET except the two alert writes, which serve POST); the Allow header lists what's permitted |
conflict |
409 | On an alert write: details.code ALERT_RESOLVED (the alert is already resolved) or ALERT_STATE_CHANGED (it changed between the read and the write; read it again). On GET /v1/reports/{id}/download: the file cannot be served as asked. details.code is REPORT_NOT_READY (still generating or failed; details.status), FORMAT_UNSUPPORTED (no renderer for that format; details.formats lists the ones there are) or FILE_TOO_LARGE (over the size cap; details.limit_bytes). See Authentication |
rate_limited |
429 | Quota exceeded; details.scope says whether it was per key, tenant, or service (write_key is a key's write budget) |
internal_error |
500 | Unexpected server error |
service_unavailable |
503 | Temporarily unavailable |
Retries¶
For 429, 500, 502, 503, and 504, retry with exponential backoff and honor the
Retry-After header when present. Don't automatically retry 400, 401, 403, 404,
or 405: the request is malformed or unauthorized, and repeating it unchanged produces
the same error. A 409 REPORT_NOT_READY with details.status generating is worth
retrying later; the other 409s are not (ALERT_STATE_CHANGED: read the alert again first).