Errors

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