API reference

Errors

Errors come back as JSON with the HTTP status, a stable name you can check in code, and a message for people:

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "The `to` field is required."
}

Error names

StatusnameWhat to do
401missing_api_keySend Authorization: Bearer <key>.
402insufficient_creditsYour plan has no email validations left this month. See Validate email addresses.
403invalid_api_keyThe key is wrong or revoked, or the account is disabled. Check the key or create a new one.
403restricted_api_keyThe key cannot do this: a sending key on a full-access endpoint, a key limited to another domain, an account without API access or without an active subscription.
403invalid_from_addressThe from domain is not verified. Verify your domain.
404not_foundNo email or key with that ID belongs to your account.
409invalid_idempotent_requestThe Idempotency-Key was already used with a different request body. Use a new key.
422validation_errorA field is missing or invalid. The message names the field.
429Too many requests. Wait for the number of seconds in the Retry-After header. See Rate limits.

Retrying

  • Retry 429 and 5xx responses with exponential backoff.
  • Do not retry 4xx errors other than 429 without changing the request.
  • Always retry with the same Idempotency-Key, so a request that actually succeeded is not sent twice. See Idempotency.