Errors & retries

Keep the same request key when retrying.

Errors

HTTP statusMeaning
400Check the JSON, E.164 number, and Idempotency-Key.
401Sign in or supply a valid Bearer API key.
402Add credits to your account.
403Request origin is invalid or billing is under review.
404The lookup does not exist in your account.
429Wait before starting more requests. Limit: 10 new lookups per minute per account. Idempotent replays do not count.
409This key was used for a different phone number or refresh setting.
503The 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