Skip to content

Errors

Every /v1 error has the same shape, including the ones produced by credential verification:

{ "error": { "code": "forbidden", "message": "…", "request_id": "…", "details": {} } }
  • code is the closed vocabulary your client should branch on.
  • message is for a human reading a log — it is not stable across versions.
  • details is diagnostic, not part of the contract.
  • request_id matches the X-Request-Id response 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).