Errors | Verifa

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 validation (e.g. 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.

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

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