Errors

Every error has the same shape, so one handler covers them all.

{
  "statusCode": 422,
  "name": "domain_not_verified",
  "message": "Sending domain \"mail.acme.com\" is not verified for this project",
  "error": {
    "code": "domain_not_verified",
    "message": "Sending domain \"mail.acme.com\" is not verified for this project",
    "request_id": "req_Kd83...",
    "details": {}
  }
}

Switch on error.code, not message. Quote the request_id if you contact support. statusCode, name and message repeat the essentials at the top level for clients that look there. name is the same as code except for a few that use more familiar names: invalid_api_key (401), restricted_api_key (403), rate_limit_exceeded (429), monthly_quota_exceeded and daily_quota_exceeded.

Status	Code	Meaning
400	`validation_error`	The request is invalid. The message names the field.
400	`invalid_variables`	A template variable is missing or has the wrong type.
401	`unauthorized`	Missing, invalid or revoked API key.
403	`forbidden`	The key lacks the needed scope.
403	`account_not_approved`	Live sending is waiting for account approval.
403	`account_suspended`	The account is paused.
403	`plan_limit_reached`	Your plan’s limit (domains, webhooks, projects…) is reached. Upgrade to add more.
404	`not_found`	No such resource in this project.
409	`not_schedulable`	You tried to reschedule or cancel an email that is not waiting for its time any more.
409	`idempotency_conflict`	The key was used with a different body.
409	`domain_already_registered`	Another project already registered this domain.
413	`payload_too_large`	The request is over 2 MiB.
422	`domain_not_verified`	The From domain is not verified in this project.
422	`recipient_suppressed`	Every recipient is suppressed.
429	`rate_limited`	Too many requests. Wait the number of seconds in `Retry-After`.
429	`daily_limit_exceeded`	The project reached its daily limit.
429	`quota_exhausted`	The monthly allowance or spend cap is used up.

What to retry

Retry network errors, timeouts and 5xx responses, with the same Idempotency-Key, and 429 after waiting.
Do not retry 4xx errors other than 429. Fix the request first.