Errors and rate limits
Error shape, status codes, and how to pace requests.
Errors are structured 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.