Errors

Errors come back as JSON with a detail field:

{ "detail": "invalid or missing X-API-Key" }

Status	`detail`	What it means	What to do
`401`	`invalid or missing X-API-Key`	The key header is missing, or the key is wrong or revoked.	Check your key.
`403`	(an HTML page)	The request was blocked before it reached the API, almost always because of a missing or default `User-Agent`.	Send a real `User-Agent` header.
`413`	`max 10000 numbers per batch`	The batch has more than 10,000 numbers.	Split it. Batches of 2,000 or fewer work best.
`422`	A list of field errors	The request is malformed: no `number` parameter, or a body that isn’t `{"numbers": [...]}`.	Fix the request.
`503`	`key store unreachable, try again shortly`	Your key couldn’t be checked for a moment.	Retry after a few seconds.
`503`	`server auth not configured`	The service isn’t ready.	Retry later.

A bad number isn’t an error

A number that isn’t a valid +1 number still returns 200, with verdict: "invalid" and the reason:

{ "phone": "+44 20 7946 0000", "phone_valid": false, "e164": null, "verdict": "invalid", "reasons": ["not a valid NANP number (format)"] }

In a batch, one bad number never fails the whole call.

Retry 503 and network errors with exponential backoff (for example 1s, 2s, 4s). Don’t retry 401, 413 or 422 without changing the request.