Skip to content
Docs Errors and rate limits

Errors and rate limits

Error shape, status codes, and how to pace requests.

Errors are structured JSON:

{}error.json
{"error": "invalid email address", "code": "INVALID_INPUT"}

Status codes

Status code What to do
400 INVALID_INPUT Fix the request body or parameters
400 INVALID_DOMAIN The domain is not a bare domain such as example.com. Fix it and retry
400 INVALID_CHECKS A checks value names a record we don’t check. Use the values on Domain authentication
401 UNAUTHORIZED Check the key; create a new one if revoked
403 FORBIDDEN The key or plan is not allowed this operation
403 PAID_PLAN_REQUIRED A live key on an account with no plan and no credits, or a sandbox AI-app connection used on a real address. Pick a plan or a credit pack; the key works at once. Test keys and sandbox connections work without one on the test addresses
403 LIVE_KEY_REQUIRED A test key was used on a real address or domain. Use a live key, or a test address at example.com
403 RESULTS_LOCKED A free-plan job’s full results are locked; fetch the summary, or buy any plan or credit pack to unlock the download
404 NOT_FOUND The job or resource does not exist
409 INVALID_STATE The job is not in a state that allows this action (for example pausing a finished job)
429 RATE_LIMITED Per-minute limit hit; back off until X-RateLimit-Reset
429 QUOTA_EXCEEDED Plan checks and credits used up. Paid plans renew monthly; the free 300 does not. Top up or upgrade
429 DAILY_LIMIT Dashboard checks only: a Free account without credits has used its 50 checks for the day. Wait until 00:00 UTC, or add a plan or credit pack
429 RERUN_COOLDOWN Unknown-rerun was used less than 30 minutes ago; wait and retry
500 INTERNAL_ERROR Retry with backoff; if it persists, check the status page

Pacing

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Plan throughput from them instead of retrying blindly. Per-minute limits by plan, counted per account across all of its keys: Free with credits 10, Starter 20, Pro 30, Business 60, Scale 300K 90, Scale 500K 120; Enterprise sets its own in the contract. A batch call counts each address. Test keys have their own limit: 60 requests a minute per account, where a batch counts 1 (see the sandbox). For large lists, bulk upload is faster and kinder than looping over single calls.

Free accounts

A Free account without credits cannot run live checks over the API: a live key answers 403 PAID_PLAN_REQUIRED. It can create test keys and build against the sandbox for free, and a sandbox AI-app connection works the same way. Its 50 checks a day apply to dashboard checks only, so 429 DAILY_LIMIT and the X-Daily-Limit and X-Daily-Remaining headers do not occur on API responses. Any plan or credit pack opens live checks and removes the daily cap.