Errors and status codes

Non-success API responses use one shape:


{
  "statusCode": 422,
  "name": "UnverifiedDomain",
  "message": "The sending domain is not verified for this organisation. Add it with POST /domains and publish the DNS records."
}

Branch on the status and name; do not depend on the exact wording of message.

HTTP status	Name	What to do
`400`	`ValidationError` or `BadRequest`	Correct the request fields or recipient count before retrying
`401`	`Unauthorized`	Check the server-side API key; it may be missing, invalid or revoked
`404`	`NotFound`	Check the message ID and organisation; inaccessible messages also return 404
`422`	`UnverifiedDomain`	Complete domain verification before sending
`422`	`Suppressed`	Do not retry sending to that recipient unchanged
`422`	`UnsupportedTag`	Only transactional email is accepted
`429`	`TooManyRequests`	Back off and retry later; honour `Retry-After` when present
`500`	`InternalServerError`	Retry cautiously with the same idempotency key

Malformed JSON, unsupported content types and oversized requests may return other 4xx responses using the same envelope.

Network failures

A connection failure can leave you unsure whether a message was accepted. Retry the same message with the same JSON idempotencyKey within the 24-hour replay window. Use bounded retries and increasing delays.

The Node client represents transport failures as ThumelaError with statusCode: 0 and code: 'NetworkError'. See Node SDK.