Errors

Errors return a machine-readable code alongside a human-readable message. Branch on the code — messages are written for people and may be reworded.

422 Unprocessable Entity · json

{
  "error": {
    "code": "validation_error",
    "message": "Request body failed validation",
    "fields": [
      { "path": "to", "message": "at least one recipient" }
    ]
  }
}

Codes

Code	HTTP	Meaning
`missing_api_key`	401	No Authorization header was sent.
`invalid_api_key`	401	The key is malformed, unknown, or revoked.
`insufficient_scope`	403	The key lacks a required scope.
`organization_paused`	403	Sending is paused for this organization.
`domain_not_owned`	403	The From domain has not been added to this organization.
`domain_not_verified`	403	The domain exists but has not completed DNS verification.
`sandbox_recipient_not_verified`	403	This recipient has not confirmed they want your mail. Applies to new accounts only.
`not_found`	404	No such resource, or it belongs to another organization.
`organization_not_provisioned`	409	The organization's sending infrastructure does not exist yet.
`idempotency_conflict`	409	The key was reused with a different body, or is in flight.
`message_too_large`	413	The message or its attachments exceed the size limit.
`validation_error`	422	The request body failed validation. See fields.
`missing_field`	422	A required field was absent.
`recipient_suppressed`	422	A recipient is suppressed after a hard bounce or complaint.
`rate_limit_exceeded`	429	Too many requests. See Retry-After.
`monthly_quota_exceeded`	429	The monthly send limit is spent. It resets on the 1st, 00:00 UTC.
`daily_quota_exceeded`	429	The daily send quota is exhausted. Resets at 00:00 UTC.
`provider_error`	502	An upstream mail provider rejected the request.
`internal_error`	500	Something went wrong. The reference maps to a log line.

What to retry

Retry 429, 502 and 500 with exponential backoff. Every4xx other than 429 is a request that will fail identically forever — retrying it only consumes your rate limit.

Retry safely

Send an Idempotency-Key on every send. A retry after a timeout then replays the original response instead of delivering a second copy to your customer.

Request references

Every response carries sreemail-request-id, and a 500 repeats it in the error message. Quote it in a support request and it maps directly to a log line.

Delivery failures are not errors

A 202 means accepted, not delivered. A bounce, a complaint or an upstream rejection happens after the response and reaches you as an event: email.bounced, email.complained, email.rejected or email.failed. Register a webhook or you will never learn about them.