This page is the error code reference for the Transactional Email API v1 and v2. Success codes are included as well, shown on a green background, so they are easy to distinguish from errors. Endpoint-specific sample responses live on each endpoint's own page; this page is the shared reference for error shapes and codes.
V2 Errors
Success: 202 Accepted
The request was validated and queued for asynchronous delivery. A 202 confirms acceptance only, not delivery. Use the delivery-status endpoint to track progress.
{
"status": "accepted",
"message_id": "550e8400-e29b-41d4-a716-446655440000"
}Duplicate: 409 Conflict
An identical request was received within the 15-minute deduplication window. The original is already being processed, and the duplicate is ignored.
{
"status": "duplicate",
"message_id": "550e8400-e29b-41d4-a716-446655440000"
}Error envelope
Every non-2xx response uses a single envelope: status, message, and an optional errors array listing each field that failed. All validation errors are collected and returned together
{
"status": "error",
"message": "validation failed",
"errors": [
"recipients[0].email is not a valid email address",
"subject is required"
]
}Send error codes
Code | Condition | Message |
|---|---|---|
400 | Malformed JSON body | invalid JSON body |
400 | One or more validation rules failed | validation failed (see errors) |
401 | Auth key missing or invalid | unauthorized |
409 | Duplicate request within the 15-minute window | duplicate request |
413 | Request body larger than 25 MB | payload too large |
429 | Rate limited (includes retry_after) | rate limited |
500 | Internal failure | internal error |
Retries and idempotency
The deduplication key is recorded only after the message is successfully queued, so a publish failure does not cause a phantom 409 on retry.
Validation endpoint responses
The validation endpoint always returns 200; the outcome is in the body.
{
"valid": true,
"rendered": [
{
"field": "subject",
"output": "<p>Hi Alice</p>"
}
]
}{
"valid": false,
"errors": [
{
"field": "content[0]",
"message": "unterminated \"for\" block"
}
]
}Category endpoint errors
Code | Error | Case |
|---|---|---|
400 | invalid_request | Malformed JSON, missing name, or unknown fields |
400 | invalid_name | name fails the naming rule |
400 | description_too_long | description is longer than 255 characters |
409 | category_exists | name already exists (body includes existing_id) |
422 | category_limit_reached | The partner has reached the maximum of 100 categories |
400 | invalid_id | A non-positive category ID was requested |
404 | not_found | No such category exists for the partner |
Delivery-status codes
Code | Case |
|---|---|
400 | message_id is not a valid UUID |
401 | Auth missing or invalid |
404 | Unknown message_id for this partner, or beyond the 2-day window |
429 | Status-endpoint rate limit exceeded |
500 | Unexpected failure |
V1 errors
V1 remains supported until summer 2027. Its responses include a status_message field and, for duplicates, a 208 status code.
Success: 202 Accepted
{
"message_id": "8e664ecd-352d-4dbd-9786-ceb78b5b173b",
"status_message": "accepted"
}208 Already processed (duplicate)
{
"message_id": "dce90e71-6786-4d69-93eb-5162a2508e15",
"status_message": "This request has already been received and is being processed. Any duplicate content from the user will be ignored for the next 15 minutes.",
"timestamp": 1762942657
}400 Bad request
Examples: missing email in tos, invalid callback URL, dynamic fields over the size limit, too many dynamic fields, or a missing required parameter.
{
"errors": [
"Missing 'email' on 'tos' parameter"
],
"status_message": "failed to validate request"
}{
"status_message": "dynamic fields total byte size exceeds the limit of 49300 bytes"
}401 Unauthorized
{
"message": "The domain you are trying to use is not authenticated. Please create a support ticket for the Insider Support Team to authenticate it.",
"status": 401
}413 Payload too large
{
"status_message": "Email payload limit exceeded"
}Transient errors (500, 502, 503, 504, 520)
These indicate a temporary server or gateway condition. The request was not processed; retry after a short delay.
For related references, refer to API Status and Error Codes and API Rate Limits.