Error codes
A failed request answers { success: false, error: { code, message, request_id } } with one of the codes below, and never costs a credit. The request_id is also sent as the X-Request-Id header; quote it when writing to support.
| code | http | when |
|---|---|---|
| UNAUTHENTICATED | 401 | The Authorization header is missing, malformed, or carries a key that does not exist or was revoked. |
| VALIDATION_FAILED | 422 | One or more fields are missing, malformed, or over a limit. error.errors lists each field with its messages. |
| RATE_LIMITED | 429 | The API allows 5 requests per second per key; the browser endpoint allows 20 lookups a minute per visitor. |
| INSUFFICIENT_CREDITS | 402 | The account has no credits left, so the lookup did not run. Free credits renew at the start of each month; packs can be bought from the Billing page. |
| RESULTS_NOT_READY | 409 | Results were requested for a bulk job that is still queued or running. |
| JOB_ALREADY_FINISHED | 409 | A cancel was requested for a bulk job that already reached a terminal status: completed, cancelled, or failed. |
| JOB_CANCELLED | 409 | Results were requested for a job that was cancelled before any address was processed, so there is no results file. |
| INVALID_PUBLISHABLE_KEY | 401 | The pk_ key sent to the browser endpoint is unknown. |
| ORIGIN_NOT_ALLOWED | 403 | The Origin header of the browser request does not match any domain the publishable key allows, or the header is missing. |
| KEY_SPEND_CAP_REACHED | 429 | The key was created with a daily credit cap and has reached it today. The counter resets each day. |
| TURNSTILE_FAILED | 403 | The key was created with a Turnstile site key and secret, and the lookup carried no token or one Cloudflare did not confirm. |
| UNKNOWN_FEEDBACK_PROVIDER | 404 | The URL POST /api/v1/email/feedback/{provider}/{key} accepts postmark, ses, mailgun and sendgrid only. |
| INVALID_FEEDBACK_KEY | 401 | The fb_ key in a bounce webhook URL does not exist or was rotated. |
Validation failures carry an extra error.errors object keyed by field. Rate-limit answers carry a Retry-After header. Each code has a Markdown twin at its URL with a .md suffix.