Errors

All error responses follow a consistent JSON format:

1 {
2   "error": "not_found",
3   "detail": "Session not found.",
4   "status_code": 404
5 }

Field	Type	Description
`error`	string	Machine-readable error code.
`detail`	string	Human-readable description of the error.
`status_code`	integer	HTTP status code.

Status codes

Code	Meaning	When it occurs
`400`	Bad Request	Malformed JSON, missing required fields, or invalid parameter values.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	API key lacks the required scope, or IP not in allowlist.
`404`	Not Found	The requested resource does not exist or belongs to a different organization.
`409`	Conflict	Resource state conflict (e.g. approving an already-approved session).
`422`	Unprocessable Entity	Request body is valid JSON but fails semantic or field-level validation (e.g. string longer than its `maxLength`, list longer than its `maxItems`, or an idempotency key reused with different parameters).
`429`	Too Many Requests	Rate limit or product quota exceeded. See Rate Limiting.
`500`	Internal Server Error	An unexpected error on our side. These are automatically reported and investigated.

Common error codes

`error` value	Status	Description
`bad_request`	400	Invalid request parameters.
`unauthorized`	401	Missing or invalid API key.
`forbidden`	403	Insufficient permissions.
`not_found`	404	Resource not found.
`conflict`	409	State conflict.
`validation_error`	422	Semantic validation failure.
`idempotency_mismatch`	422	Same idempotency key used with different parameters.
`rate_limited`	429	Rate limit exceeded.
`quota_exceeded`	429	Product quota exceeded.
`internal_error`	500	Unexpected server error.

Field-level validation (422)

Request bodies for sessions, cases, identities, and screening enforce strict field bounds. Violations return 422 Validation Error with a detail array naming each offending field. Common triggers:

String fields exceeding their maxLength (typically 100, 500, or 5000 characters depending on the field).
Lists exceeding their maxItems (typically 50 tags or 100 items).
The metadata object exceeding 16 KB serialized.

Fix the request body before retrying — these errors are not transient.

Retry guidance

Status code	Retry?	Notes
400, 401, 403, 404	No	Fix the request before retrying.
409	No	Resolve the conflict (e.g. check current resource state).
422	No	Fix the request body or use a new idempotency key.
429	Yes	Wait for the `Retry-After` duration, then retry.
500	Yes	Retry with exponential backoff (max 3 attempts).

Authentication — 401 and 403 error details
Rate Limiting — 429 response handling and quotas
Idempotency — 422 idempotency mismatch errors

Status codes

Common error codes

Field-level validation (422)

Retry guidance

Related