Errors

5 min

All v1 errors share one envelope. Build your error handling around the stable code field — not the human-readable message.

The error envelope

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account is out of verification credits.",
    "type": "billing_error",
    "request_id": "req_a1b2c3"
  }
}

Field	Use it for
code	Branch on this. A stable, machine-readable slug. Adding new codes is non-breaking; renaming one is a major-version change.
message	Display / logging only. Wording can change at any time — never pattern-match on it.
type	Coarse category, derived deterministically from the HTTP status (see below). Handy for grouping.
request_id	Echoes the X-Request-Id response header. Quote it in support tickets so we can trace the request.

Error categories (type)

type is a function of the HTTP status code:

HTTP status	type
400, 405, 413, 415	invalid_request_error
401, 403	authentication_error
402	billing_error
404	not_found_error
409	conflict_error
429	rate_limit_error
5xx	api_error

HTTP status codes

Status	Meaning
200	Success.
400	Invalid request — missing or malformed parameter.
401	Invalid credentials — key rejected.
402	Payment required — out of credits (insufficient_credits).
403	Forbidden — credentials valid but policy/scope/origin denies.
404	Not found — the resource doesn't exist or belongs to another account.
409	Conflict — a request with the same Idempotency-Key is still running.
413	Payload too large.
415	Unsupported media type — Content-Type must be application/json.
422	Same Idempotency-Key reused with a different request body.
429	Rate limited — honor Retry-After. See the Rate limits guide.
500	Server error — likely a bug. Retry once with backoff.
502, 503, 504	Upstream unavailable. Retry with backoff.

Common error codes

Branch on these slugs. The list is grouped by category; see the API reference per-endpoint for which codes each can return.

Authentication & permission — missing_api_key, invalid_api_key, forbidden, domain_not_authorized.

Input validation — missing_email, invalid_email, missing_emails, invalid_emails, missing_job_id, invalid_job_id, invalid_content_type, invalid_request.

Limits — payload_too_large, rate_limited.

Billing — insufficient_credits.

Not found / conflict — not_found, job_not_found, job_not_completed, idempotency_key_in_progress (409), idempotency_key_fingerprint_mismatch (422).

Server / upstream — job_creation_failed, job_fetch_failed, delete_failed, timeout, server_error, service_unavailable.

Recommended handling

Switch on the HTTP status for coarse control flow (retry vs. fail).

Within a status, switch on error.code for specific handling (e.g. insufficient_credits → prompt a top-up).

Log error.request_id alongside your own context, and quote it in any support ticket.

For 429 and 5xx, retry with exponential backoff — honor Retry-After when present.