Errors & retries
Keep the same request key when retrying.
Errors
| HTTP status | Meaning |
|---|---|
| 400 | Check the JSON, E.164 number, and Idempotency-Key. |
| 401 | Sign in or supply a valid Bearer API key. |
| 402 | Add credits to your account. |
| 403 | Request origin is invalid or billing is under review. |
| 404 | The lookup does not exist in your account. |
| 429 | Wait before starting more requests. Limit: 10 new lookups per minute per account. Idempotent replays do not count. |
| 409 | This key was used for a different phone number or refresh setting. |
| 503 | The service is unavailable or the lookup failed. Failed lookups spend no credit. |
Ambiguous timeouts
Allow up to 120 seconds for a request. If the connection drops, repeat the exact request with the same Idempotency-Key. A 202 result contains an ID to poll. The same key returns the original result and cannot charge again.
A timed-out server request releases its reserved credit when its status or account dashboard is read, or another lookup starts. An expired request cannot later spend that credit.
New attempts
To intentionally run again after a terminal failure or no match, use a new key. Changing refresh also requires a new key. Keys are scoped to your account and accept 8–128 letters, digits, or ._:-.
Credits & billing