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.
For more detailed information about these errors and how to fix them, see the error reference on Send Transactional Emails via API V2.
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.