Error Handling

What It Does

When something goes wrong, the API tells you what in a stable shape and hands back a correlation ID you can quote to support to find the exact log line. Client mistakes (a bad field, a missing permission) come back with a clear message; genuine server faults are deliberately kept vague to the caller so nothing sensitive leaks — the full detail is in your instance’s logs.

Many refusals also carry a short machine-readable code, so software calling the API can react correctly without reading the sentence: wait, ask the person to sign in again, or show an upgrade prompt. The full list is at the end of this page.

Errors raised through the shared error handler come back in one envelope, so your integration can branch on structure instead of parsing prose. A few refusals issued by guards in front of the handler use a simpler shape; they are listed below.

The Error Envelope

• error is always a string. When a connected vendor answers with an error object, the handler flattens it to its message before replying.
• code is included only below 500. A server fault never carries one through this handler.
• The gateway generates the correlation ID for every request and returns it in the x-correlation-id response header, on success and failure alike; a value sent by the client is discarded. The one reply without the header is the cross-site request check refusal below, which is answered before a correlation ID is assigned.
• A 401 from a connected vendor (a rejected directory credential, for example) is returned to you as 400, so it cannot be mistaken for your own session expiring.
• An unknown path answers 404 { "error": "Not found" } as JSON, with no correlationId in the body.

Refusals That Do Not Use The Envelope

Guards that run in front of the handler, and controllers that reply directly, send smaller bodies. None of these has a correlationId in the body; read the x-correlation-id response header instead (the cross-site request check refusal has neither).

• Direct controller reply: { "error": "…", "code": "MACHINE_CODE" }. Most coded refusals in the table below are sent this way, and a few add fields of their own (missing, conflicts, replacement).
• Step-up required: { "error": "SUDO_REQUIRED", "message": "This action requires re-authentication" }. The machine code is in error and there is no code. Where the gateway forwards the call itself and answers through the shared error handler, message is replaced by a correlationId. A missing or expired step-up is refused with "error": "SUDO_REQUIRED" in the response body. The status beside it is 400 on most routes, because the gateway turns a 401 from a service behind it into 400. It stays 401 on the routes the gateway passes through unchanged: removing a passkey, the diagnostics bundle, and in Security Lab starting an aggressive scan, changing a scan scope and archiving findings. Key on the error string, not the status.
• Session not valid: 401 { "auth": false, "message": "Session invalid or expired" }, passed through from session validation. There is a message and no error. When the account itself is no longer active the gateway adds error and "code": "SESSION_NOT_ACTIVE".
• Second factor not completed: 403 { "error": "MFA Required", "message": "Multi-Factor Authentication is required to perform this action." }.
• Rate limits: 429 { "error": "Too many authentication attempts. Please try again later." } — an error string only.
• Subscription lapsed: 402 { "error": "Subscription lapsed", "message": "…" }.
• Not in your plan: 403 { "error": "License Required", "message": "…" }.
• Cross-site request check: 403 { "error": "CSRF check failed: missing or untrusted Origin." }, for a cookie-authenticated write with no trusted Origin. This reply carries no x-correlation-id header.
• Network or location block: 403 { "error": "Access denied." }, with no further detail by design.
• Read-only support session: 403 { "error": "Support session is read-only", "message": "…" }.
• Finance endpoints: the finance service answers its own validation and conflict errors as { "detail": "…" }, and the gateway forwards that body unchanged. Its guards (request too large, subscription lapsed, not in your plan) use { "error": "…", "message": "…" }.
• SCIM endpoints: errors use the SCIM error schema, { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "429", "detail": "…" }, with scimType where the standard defines one.

A client that handles all of these reads the status first, then code, then a machine word in error, and shows whichever of error, message or detail is present.

Status Codes You’ll See

This table is the one place the meaning of each status number is kept, and the Error Code Reference at the end of this page is the one place for each machine-readable code. Other pages link here. To look a failure up by the message you received, use API Error Troubleshooting.

A plan refusal carries no code. Tell “not in your plan” from “broken” by the status and the fixed error string — 402 with Subscription lapsed, 403 with License Required — so your UI can prompt a renewal or an upgrade instead of showing a generic failure.

Retry-After And Rate-Limit Headers

Three replies set Retry-After (in seconds) themselves. Honour it rather than retrying on a fixed timer.

The gateway’s own rate limits answer 429 with the standard RateLimit-* response headers and without the older X-RateLimit-* ones. Read RateLimit-Reset for when to try again. The second-factor limiter, which guards the /auth/mfa/* routes and the passkey registration and sign-in routes under /auth/webauthn/*, is the exception: its configuration does not select a header set, so do not rely on RateLimit-Reset on those routes. Its window is 5 minutes; after a 429 there, wait up to 5 minutes. The body is an error sentence with no code; on the SCIM endpoints it is a SCIM error body.

Retries: What Is Safe To Send Again

In plain words: reading something twice is harmless; creating something twice can leave you with two of it. The API does not recognise a repeated request by itself, so your script has to know which requests it may repeat.

• GET and HEAD are safe to repeat. They do not change your records. Repeat them after any error or timeout.
• PUT is safe to repeat with the same body. A PUT replaces a record or a setting with what you send, so sending it twice ends in the same state. The API adds nothing of its own to guarantee this; it follows from the method.
• DELETE is normally safe to repeat. Once the record is gone there is nothing left to remove. The status of the second call differs by route (often 404); treat any 4xx on the repeat as already done and confirm with a read.
• POST is not deduplicated. Unless a route’s own entry says it accepts an idempotency key, none is read, so a POST that is sent twice is handled twice. If a POST times out, read back before sending it again. Treat PATCH the same way unless its entry says it only sets fields to the values you send.

What 409 means

409 says the request was understood and not applied, because it conflicts with what is already there. The same request keeps getting 409 until that state changes, so do not retry it on a timer. Three cases come up most:

• It already exists. Creating a user whose email is taken, or a role whose name is taken, answers 409. After a create that timed out, a 409 on the second attempt usually means the first one went through: read the record to confirm.
• Something is already in progress. Update, backup, restore and backup-deletion requests share one pending slot. A second request while one is waiting for approval or running answers 409. Wait for it to finish, or have it rejected or cancelled (see Backup, Restore & Updates).
• The record changed or the step is out of order. Reload the record and decide again. Many of these carry a code; the table at the end of this page says what each one needs.

Three POST routes whose repeat is known

• Creating a SCIM user twice. POST /scim/v2/Users for an address that a live account already has answers 409 with scimType uniqueness. Nothing is created the second time.
• Marking notifications read. POST /user-management/notifications/:id/read and /read-all only touch notifications that are still unread, so repeating either changes nothing.
• Confirming an authenticator app twice. A second POST /auth/mfa/setup/confirm with a valid code is accepted. Recovery codes are issued only when the account has none, so the repeat answers recoveryCodes: null: keep the codes from the first reply.

In the API reference, many write rows say in their guard line what a repeat does, after the word Repeat. Not every write row carries one.

By status

Set your client’s own timeout with the gateway’s in mind: by default it waits up to 300 seconds for a service before answering 504. A client that gives up sooner cannot tell whether a write was applied, and should read back before repeating it. What each outage looks like is on Failure Modes.

Error Code Reference

The machine-readable words the API puts in an error body, grouped by subject. Unless a row says otherwise the word is the value of code. Rows marked “in error” carry it in the error field and have no code. Branch on the status together with the word: a few words are reused by different services.