API reference
Errors and limits
Errors use standard HTTP status codes and a consistent JSON body.
Error body
{"error": {"code": "invalid_api_key", "message": "API key not recognised or revoked"}}| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | The body or parameters are invalid. The message says what's wrong. |
| 401 | missing_api_key | No key was sent. |
| 401 | invalid_api_key | The key doesn't exist or was revoked. |
| 402 | quota_exceeded | Your monthly quota is used up. Upgrade or wait for the 1st. |
| 403 | restricted_api_key | A verify-only key called an endpoint other than /v1/verify. |
| 403 | workspace_suspended | The workspace has been suspended. Contact support. |
| 404 | not_found | The job doesn't exist in your workspace. |
| 413 | too_many_emails | A job can hold at most 500,000 addresses. |
| 429 | rate_limited | Too many requests this minute. Retry after the Retry-After header. |
| 500 | internal | Something went wrong on our side. Safe to retry. |
Rate limits
Each workspace has a per-minute request limit shared by all its keys: 60 on Free, rising to 1,200 on Scale (see pricing). Over the limit you get 429 with Retry-After: 60. A bulk job counts as one request however many addresses it holds.
Quotas
Every verified address counts towards your monthly quota, including cached results and addresses in bulk jobs, except results that come back unknown, which are free. Quotas reset at 00:00 UTC on the 1st. Check where you are with /v1/usage or on the dashboard.