Get started

Errors and limits

What a failed request looks like, and how much you can do on each plan.

Errors

A failed request returns an error status and a JSON body with a type you can handle in code and a message that explains what went wrong.

Error

{
  "error": {
    "type": "recipient_blocked",
    "message": "Some recipients are on the block list",
    "addresses": ["old-address@example.com"]
  }
}

Types you may want to handle: invalid_request_error, authentication_error, not_found_error, conflict_error, recipient_blocked, send_limit, send_failed and idempotency_error.

Status codes

Status	Meaning
`200`	Success.
`201`	Created.
`302`	Redirect to a download link.
`400`	The request is invalid. The message says what to fix.
`401`	The API key is missing, wrong or revoked.
`403`	Your account cannot use this endpoint, or the method and path do not exist.
`404`	Not found, or it belongs to another account.
`409`	Conflict, such as an email address that is already taken or a disabled inbox.
`413`	The upload is too large.
`422`	Understood but refused, such as a blocked recipient.
`429`	Too many requests, or the monthly limit is reached.
`500`	Something went wrong on our side. Try again later.
`502`	The email could not be sent, or search is briefly unavailable.

Limits

Limits depend on your plan and are shared by all your keys. Every account starts on Starter.

Plan	Requests / second	Requests / month	Emails sent / month
Starter	1	1,000	100
Basic	5	10,000	1,000
Pro	20	100,000	10,000
Business	50	500,000	50,000
Enterprise	100	2,000,000	250,000

Short bursts of up to twice the per-second rate are allowed. Over the limit you get 429. Monthly counts reset on the first day of the month; check yours with Get usage.

Retrying safely

Retry 429, 500 and network errors after a short wait, waiting longer each time.
Do not retry 4xx errors other than 429 without changing the request.
When sending email, always set an Idempotency-Key. Retrying with the same key never sends the email twice; you get the original response back.