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.
`401`	`unauthorized`	Missing, malformed, invalid, or revoked API key.
`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.
`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: ...`.
`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 — the codes are stable; the messages are for humans and may change.
500 responses are retryable.
403 domain errors are configuration problems: fix them in the dashboard rather than retrying.

Send failures are asynchronous

Sending is queued, so a provider rejection never surfaces as an HTTP error on submit. Retransmit retries transient provider failures automatically with exponential backoff; an email that exhausts its retries is dead-lettered and marked failed with the provider’s message in error. Detect failures via Get Email / Get Batch, or subscribe to the email.failed webhook.