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).

VALIDATION_FAILED

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.

MISSING_FIELD

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.

INVALID_INPUT

Typical HTTP status
400
Retryable
no
Meaning
A field is present but malformed: wrong type, bad format, out of range, or an unknown enum value.
Remediation
Fix the offending field per the OpenAPI schema and resend. Retrying unchanged will fail again.

CSRF_INVALID

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.

CSRF_MISSING

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.

HONEYPOT_TRIGGERED

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.

CAPTCHA_FAILED

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.

HASHCASH_FAILED

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.

SECURITY_CHECK_FAILED

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.

UNAUTHORIZED

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.

FORBIDDEN

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.

ENTITLEMENT_MISSING

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.

NOT_FOUND

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.

CONFLICT

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).

BUSINESS_RULE_FAILED

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.

RATE_LIMITED

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).

EMAIL_DELIVERY_FAILED

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.

INTERNAL_ERROR

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.

DATABASE_ERROR

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.