API error codes
Every API error returns a JSON envelope with a stable machine-readable code and a help_url pointing at an anchor on this page. Machine-readable form: GET /api/docs/errors (JSON).
- Typical HTTP status
- 422
- Retryable
- no
- Meaning
- The request was well-formed but its data failed server-side validation rules.
- Remediation
- Inspect the "details" object for per-field errors, correct the payload, and resend. Retrying unchanged will fail again.
- Typical HTTP status
- 400
- Retryable
- no
- Meaning
- A required field is absent from the request payload.
- Remediation
- Add the missing field named in "message"/"details" and resend. Check the OpenAPI spec (/api/docs/openapi.json) for the required request shape.
- Typical HTTP status
- 403
- Retryable
- yes
- Meaning
- The supplied CSRF token did not match the server-side expectation (stale, rotated, or forged).
- Remediation
- Fetch a fresh token (GET /api/auth/csrf or /security/csrf/token), set it in the X-CSRF-Token header, and retry. Frontends must use @itt/platform-http (authedFetch), which handles this automatically.
- Typical HTTP status
- 403
- Retryable
- yes
- Meaning
- A state-changing request arrived without a CSRF token.
- Remediation
- Obtain a token (GET /api/auth/csrf) and send it as X-CSRF-Token on every mutating call, then retry.
- Typical HTTP status
- 400
- Retryable
- no
- Meaning
- A hidden anti-bot honeypot field was filled in, so the submission was classified as automated spam.
- Remediation
- Do not populate hidden form fields. If a legitimate client hits this, stop auto-filling all inputs programmatically.
- Typical HTTP status
- 403
- Retryable
- yes
- Meaning
- The captcha answer was wrong, expired, or missing.
- Remediation
- Request a new captcha challenge (/security/captcha), solve it, include the solution, and retry.
- Typical HTTP status
- 403
- Retryable
- yes
- Meaning
- The hashcash proof-of-work attached to the request was missing, stale, or did not meet the required difficulty.
- Remediation
- Fetch fresh hashcash parameters (/security/hashcash), recompute the proof, and retry the request with it.
- Typical HTTP status
- 403
- Retryable
- no
- Meaning
- A composite security check (origin, signature, challenge chain, or similar) rejected the request.
- Remediation
- Verify the request origin, headers, and any required signatures/challenges. Quote the "requestId" when contacting support.
- Typical HTTP status
- 401
- Retryable
- no
- Meaning
- No valid authentication credential accompanied the request (missing/expired JWT, cookie, or API key).
- Remediation
- Authenticate first (POST /api/auth/login or supply X-API-Key + X-Tenant-Id on API hosts), then repeat the call with the credential attached. Refresh expired tokens via /api/auth/refresh-token.
- Typical HTTP status
- 403
- Retryable
- no
- Meaning
- The caller is authenticated but lacks permission: wrong role, missing action permission, another tenant's resource, or a plan tier that does not include the module.
- Remediation
- Check role/action permissions and tenant scope. A 403 on a module route can also mean "wrong plan" — GET /api/billing/upgrade-paths shows the way out.
- Typical HTTP status
- 403
- Retryable
- no
- Meaning
- The caller is authenticated, but the current tenant has no active booking for the requested paid feature.
- Remediation
- Check details.feature and open details.booking_path (My Apps offers: /my-apps?tab=offers) to book the feature for this tenant. Retry after the entitlement becomes active; repeating an unchanged request does not grant access.
- Typical HTTP status
- 404
- Retryable
- no
- Meaning
- The requested resource does not exist, was deleted, or belongs to a different tenant (deliberately indistinguishable).
- Remediation
- Verify the identifier and the tenant context. Re-list the parent collection to obtain current ids.
- Typical HTTP status
- 409
- Retryable
- yes
- Meaning
- The request conflicts with the current server state: optimistic-concurrency version mismatch, duplicate creation, or an illegal state transition.
- Remediation
- Reload the resource to get its current state/version, reapply your change on top, and retry (see the app-state example for the canonical 409 round-trip).
- Typical HTTP status
- 422
- Retryable
- no
- Meaning
- The request is syntactically valid but violates a domain rule (e.g. statutory constraint, quota, lifecycle rule).
- Remediation
- Read "message"/"details" for the violated rule. The request must change semantically — blind retries will keep failing.
- Typical HTTP status
- 429
- Retryable
- yes
- Meaning
- Too many requests from this client/identity inside the current window.
- Remediation
- Back off and retry after the window resets (honour a Retry-After header when present; otherwise use exponential backoff with jitter).
- Typical HTTP status
- 502
- Retryable
- yes
- Meaning
- The server accepted the request but the downstream mail delivery (SMTP relay) failed.
- Remediation
- Retry later; the mail system may be temporarily unavailable. If it persists, report the "requestId" to support.
- Typical HTTP status
- 500
- Retryable
- yes
- Meaning
- An unexpected server-side error occurred. Details are logged server-side under the returned "requestId".
- Remediation
- Retry once after a short delay. If it persists, report the "requestId" to support — it correlates directly with the server log entry.
- Typical HTTP status
- 500
- Retryable
- yes
- Meaning
- A database operation failed unexpectedly (connectivity, lock timeout, or constraint outside normal validation).
- Remediation
- Retry after a short delay. Persistent failures indicate a server-side incident — report the "requestId" to support.