Limits and errors
Allowances
Section titled “Allowances”Allowances count addresses verified through the API, per account, per UTC hour and UTC day. The whole submission has to fit: a call that would go over is refused in full, never half-accepted. Polling and reading results are never counted. Allowance per plan →
A 429 response carries the numbers:
| Header | |
|---|---|
X-RateLimit-Limit-Hour, X-RateLimit-Remaining-Hour | This hour (limit 0 and remaining unlimited when there’s no cap) |
X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day | Today (UTC) |
X-RateLimit-Reset | When the next window starts (ISO 8601) |
Separately, each IP address can make about 20 requests per second to the API. Poll every 10–30 seconds; there’s no benefit in polling faster.
Errors
Section titled “Errors”Errors come back as JSON with a detail field — usually a sentence, sometimes an object with a code.
{"detail": "Invalid API key"}| Code | Meaning | What to do |
|---|---|---|
400 | Nothing to verify after removing duplicates, or too many addresses | Check the request |
401 | Missing or invalid API key (Missing API key. Include X-API-Key header. / Invalid API key) | Check the X-API-Key header; the key may have been revoked |
402 | Not enough credits, or no active plan with credits | Top up or renew under Plans & Billing |
403 | The account has no API access yet (trial), the key lacks the write scope, or the endpoint is dashboard-only | Make a purchase to unlock the API; use a read/write key |
404 | Job or key not found (or not yours) | Check the ID |
408 | /v1/verify/single didn’t get an answer within 30 seconds; the credit is refunded | Retry, or use a bulk job |
422 | Invalid request: a malformed address, more than 50,000 addresses, or a rejected webhook_url (the reason is in detail) | Fix the request; nothing was charged |
429 | Over your hourly or daily API allowance | Wait for X-RateLimit-Reset, or upgrade — new limits apply instantly |
503 | New jobs are briefly paused ("code": "submissions_paused", Technical maintenance) | Retry after the Retry-After header. Running jobs are unaffected and nothing was charged |
500 | The job couldn’t be queued; any credits taken are refunded | Retry; if it keeps happening, contact us |
A 429 example:
{"detail": "This submission of 20,000 verification(s) exceeds your plan's daily API budget of 10,000. Upgrade your plan to raise it — new limits apply instantly and your usage counters reset."}Job statuses
Section titled “Job statuses”status | terminal | Meaning |
|---|---|---|
queued | false | Waiting to start |
processing | false | Running |
completed | true | Finished; Unknown results refunded |
failed | true | Stopped with an error; unanswered addresses refunded |
interrupted | true | Stopped early; it may be resumed on our side |
cancelled | true | Cancelled |