Limits and errors
Rate limits
Limits depend on your plan. GET /account returns the ones that apply to your key in limits.
| Plan | Requests per minute | Rows per batch | Batches at once |
|---|---|---|---|
| Free | 60 | 100 | 1 |
| Basic | 600 | 100,000 | 3 |
| Basic+ | 1,200 | 100,000 | 5 |
These are the current values. GET /account is the source of truth.
Every response carries three headers:
| Header | Meaning |
|---|---|
RateLimit-Limit |
Requests allowed in the current window |
RateLimit-Remaining |
Requests left in the current window |
RateLimit-Reset |
Seconds until the window resets |
Over the limit the API answers 429 with a Retry-After header, in seconds. Wait that long and retry.
{
"error": {
"type": "rate_limit",
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry in 12 seconds.",
"request_id": "req_4b5c6d7e8f9a0b26"
}
}Size limits
| What | Limit |
|---|---|
email |
1,024 characters |
| Addresses in a JSON batch | 10,000 |
| JSON body | 2 MB |
| CSV file | 10 MB and 100,000 data rows |
Batch name |
120 characters |
Idempotency-Key |
255 characters |
Page of batches (limit) |
100, default 20 |
Page of results (limit) |
1,000 as JSON, 10,000 as CSV, default 100 |
A mailbox verification |
30 seconds, then 503 verification_timeout |
The error format
Every error has the same shape:
{
"error": {
"type": "invalid_request",
"code": "missing_parameter",
"message": "The email field is required.",
"param": "email",
"request_id": "req_4b5c6d7e8f9a0b1c"
}
}| Field | Meaning |
|---|---|
type |
The broad class of the error |
code |
Stable and machine-readable. Branch on this |
message |
For humans. Do not parse it. English by default, Spanish with Accept-Language: es |
param |
The request field the error refers to, when there is one |
request_id |
Same value as the X-Request-Id response header. Quote it when you write to support |
New code values may be added without a version change. Treat a code you do not know as its type.
Error codes
| HTTP | type |
code |
Meaning | What to do |
|---|---|---|---|---|
| 400 | invalid_request |
invalid_json |
The body is not valid JSON | Fix the request |
| 400 | invalid_request |
missing_parameter |
A required field is missing (see param) |
Fix the request |
| 400 | invalid_request |
invalid_parameter |
A field or query parameter has a value that is not accepted (see param) |
Fix the request |
| 400 | invalid_request |
batch_empty |
The batch has no addresses | Send at least one |
| 400 | invalid_request |
batch_too_large |
More rows than your plan accepts in one batch | Split the list |
| 400 | invalid_request |
csv_invalid |
The file is not a readable UTF-8 CSV with a header row | Fix the file |
| 400 | invalid_request |
csv_column_not_found |
No header matches email_column |
Send the exact header name |
| 401 | authentication |
missing_api_key |
No Authorization: Bearer header |
Send your key |
| 401 | authentication |
invalid_api_key |
The key does not exist | Check the key |
| 401 | authentication |
revoked_api_key |
The key was revoked | Use a current key |
| 402 | payment_required |
insufficient_credits |
Not enough credits of the type the request needs | Top up. See Credits and billing |
| 403 | permission |
mode_not_allowed |
The account may not use that mode |
Check limits.modes in GET /account |
| 403 | permission |
account_suspended |
The account is suspended | Write to support |
| 404 | not_found |
not_found |
The resource does not exist, belongs to another account or has expired | Check the identifier |
| 409 | conflict |
idempotency_key_reused |
Same Idempotency-Key, different body |
Use a new key |
| 409 | conflict |
idempotency_in_progress |
The first request with that key is still running | Wait and retry |
| 409 | conflict |
batch_not_cancelable |
The batch is already completed or failed |
Nothing to cancel |
| 413 | invalid_request |
payload_too_large |
The body is over 2 MB (JSON) or 10 MB (CSV) | Split the list |
| 415 | invalid_request |
unsupported_media_type |
Wrong Content-Type |
Use application/json, or multipart/form-data for CSV batches |
| 429 | rate_limit |
rate_limit_exceeded |
Too many requests | Wait Retry-After seconds |
| 429 | rate_limit |
concurrent_batches_exceeded |
Too many batches running at once | Wait for one to finish |
| 500 | api_error |
internal_error |
Unexpected error on our side | Retry with the same Idempotency-Key |
| 503 | api_error |
engine_unavailable |
The verification engine is unavailable. Nothing was charged | Retry later |
| 503 | api_error |
verification_timeout |
The check did not finish in time. Nothing was charged | Retry later, or use a batch |
What to retry
| Answer | Retry? |
|---|---|
| Network error or timeout | Yes, with the same Idempotency-Key |
429 |
Yes, after Retry-After |
500, 503 |
Yes, with an increasing wait between attempts |
409 idempotency_in_progress |
Yes, after a short wait |
400, 401, 402, 403, 404, 413, 415 |
No. The answer will not change until the request or the account changes |
Double the wait after each failed attempt and stop after a few. An error never charges credits.
A verification that answers 200 with verdict unknown is not an error: see Verdicts and reason codes.