Errors

Every API returns errors in the same shape:

{
  "error": {
    "code": "invalid_request",
    "message": "The field 'email' is required.",
    "request_id": "req_123"
  }
}

Include request_id when you contact support.

Status codes

Status	Code	What to do
`400`	`invalid_request`	Fix the request. Retrying won't help.
`401`	`unauthorized`	Check that your API key is correct and hasn't been revoked.
`402`	`insufficient_credits`	Add credits or turn on auto top-up, then retry.
`403`	`pro_required`	Subscribe to Pro. Live requests to paid products need it.
`403`	`account_suspended`	Contact support.
`403`	`forbidden`	Your key can't access this resource.
`404`	`not_found`	Check the ID, and test versus live mode.
`409`	`conflict`	The resource can't do that now, such as canceling a submitted verification.
`409`	`idempotency_key_reused`	Use a new `Idempotency-Key` for a different request.
`409`	`request_in_progress`	The first attempt is still running. Retry shortly.
`409`	`retry_later`	Wait the seconds in `Retry-After`, then retry.
`413`	`payload_too_large`	Send a body under 1 MB.
`429`	`rate_limited`	Wait, then retry. See limits.
`500`	`internal_error`	Retry with backoff.
`503`	`service_unavailable`	Retry with backoff.

Branch on code, not on message: codes are stable, and messages may be reworded.

Every response, successful or not, also carries the ID in an X-Request-Id header.

Add an Idempotency-Key header to POST requests. Any unique string up to 255 characters works, such as a UUID.

If the first request succeeded, a retry with the same key returns that same response, with an Idempotent-Replayed: true header, and the work isn't done twice.
If the first request was refused or failed, nothing is remembered, so a retry runs it again.
Keys are remembered for 24 hours, separately for test and live mode.