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.

JSON
{
  "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:

JSON
{
  "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.

View this page as Markdown