Errors

All errors share one shape:


{
  "error": {
    "code": "some_error_code",
    "message": "Human-readable explanation"
  }
}

Error codes

HTTP status	Code	Meaning
`400`	`invalid_json`	The request body could not be parsed as JSON.
`400`	`invalid_idempotency_key`	`Idempotency-Key` is empty or longer than 256 characters.
`401`	`unauthorized`	Missing, malformed, invalid, or revoked API key.
`402`	`quota_exceeded`	The plan’s included emails are used up and no payment method is on file, or SMS or WhatsApp was sent without one. The body also carries `limit` and `used`.
`403`	`domain_not_found`	The `from` domain is not registered on your account.
`403`	`domain_not_verified`	The `from` domain is registered but not verified.
`404`	`not_found`	The resource or route does not exist.
`409`	`invalid_idempotent_request`	`Idempotency-Key` was already used in the last 24 hours with a different body. Change the key or the body.
`409`	`concurrent_idempotent_requests`	Another request with this `Idempotency-Key` is still running. Retry shortly.
`413`	`payload_too_large`	The request body is over 43 MB. Attachments may total 30 MB before base64 encoding.
`422`	`validation_error`	A request field failed validation. The message names the field, e.g. `subject: String must contain at least 1 character(s)`. For batches it includes the index: `emails.42.subject: ...`.
`422`	`invalid_attachment`	An attachment has a blocked file type, is over the size budget, or its `path` could not be fetched. The message names the file.
`422`	`no_route`	No SMS provider is configured for the destination country.
`422`	`no_whatsapp_account`	No connected WhatsApp number matches the request. Connect one in the dashboard, or fix `from`.
`500`	`internal_error`	Something went wrong on Retransmit’s side. Safe to retry.

Handling errors

Treat any non-2xx response as a failure and read error.code. Codes are stable. Messages are for humans and may change.
500 responses are retryable. Send an Idempotency-Key on email sends so a retry cannot queue the same email twice. See Send Email: Idempotency.
409 concurrent_idempotent_requests is retryable after a short wait. 409 invalid_idempotent_request is not: the key was used with a different body.
403 domain errors are configuration problems. Fix them in the dashboard instead of retrying.
402 quota_exceeded is not retryable. Add a payment method or change plan in the dashboard . Emails past the plan’s included volume are billed at the overage rate once a card is on file; SMS and WhatsApp are pay as you go on every plan and always need one.
422 no_route means the destination country has no SMS provider yet.
422 no_whatsapp_account means no WhatsApp number is connected. Connect one in the dashboard before sending.

Send failures are asynchronous

Sending is queued, so most provider rejections do not appear as HTTP errors. Retransmit retries transient provider failures with exponential backoff. A message that exhausts its retries is marked failed with the provider’s message in error. Detect failures through Get Email, Get Batch, Get SMS, or Get WhatsApp, or subscribe to the email.failed, sms.failed, and whatsapp.failed webhooks.