Error Codes

This page is a reference for error codes returned by the Telnyx Email API. It covers two distinct families: synchronous HTTP errors returned on the API request itself, and asynchronous delivery errors (the 30xxx taxonomy) reported later via webhooks and detail records. They are not interchangeable — a 30xxx code never appears in an HTTP response body, and an HTTP code never appears in error_evidence. For endpoint-specific errors, see the response examples in each endpoint’s API reference.

Error response format

Most errors follow the standard Telnyx v2 error shape (exceptions: batch errors use {index, code, message} — see Batch-specific errors — and some template render errors use {code, message}):

{
  "errors": [
    {
      "code": "10015",
      "title": "Validation Failed",
      "detail": "subject can't be blank"
    }
  ]
}

Field	Description
`code`	Machine-readable error code (see table below).
`title`	Short human-readable summary.
`detail`	Specific error message with context.

Request and message size limits

Size failures are a common source of confusion because three different ceilings apply at three different layers. They are not the same number.

Limit	Value	Enforced by	Failure mode
Message body (`html_body` + `text_body`, decoded)	1 MB	Email API	`422` with code `10015`, title “Bad Request”, detail “body exceeds size limit (maximum 1 MB)“
Total message (decoded body + decoded attachments)	25 MB	Email API	`422` with code `10015`, title “Bad Request”, detail “message exceeds size limit (maximum 25 MB)“
HTTP request body	150 MB	Phoenix request parser	`413` with code `10015`
Idempotency-keyed replay capture — single sends	8 MB	Telnyx Edge (API gateway)	`413 Payload Too Large` — an idempotency-keyed request over 8 MB is rejected at Edge before reaching the Email API. Unkeyed requests are not subject to this cap.
Idempotency-keyed replay capture — batch sends	20 MB	Telnyx Edge (API gateway)	`413 Payload Too Large` — a keyed batch request over 20 MB is rejected at Edge before reaching the Email API. Unkeyed requests are not subject to this cap.

The edge caps are not request-body limits. They are the Edge gateway’s request_body_cap_bytes for idempotency-keyed replay only. A keyed request over its cap is rejected at the Edge with 413 Payload Too Large — it never reaches the Email API. Unkeyed requests bypass these caps entirely. Single sends cap at 8 MB; the batch endpoint caps at 20 MB. The limits that actually reject a message body are the 1 MB body and 25 MB total enforced by the Email API, which return 422.

Attachments are base64-encoded in the request, so a 25 MB message occupies roughly 33 MB on the wire. The Email API measures decoded bytes.

HTTP status codes

Status	Meaning	When
200	OK	Successful request or idempotent replay.
201	Created	Resource created (e.g. template creation).
202	Accepted	Email accepted for sending (queued).
207	Multi-Status	A batch that passed request-wide admission and reached item processing. `data` contains successes and `errors` contains item-level failures; request-wide gates can instead return 4xx/5xx.
400	Bad Request	Validation error, malformed body, or invalid `Idempotency-Key` header.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Domain not verified/suspended/degraded, sender address not allowed, shared domain is read-only, or the account is inactive.
404	Not Found	Resource (email, template, domain) not found.
409	Conflict	A request with the same `Idempotency-Key` is still being processed, or a resource conflict (e.g. deleting an unsubscribe group with active suppressions).
413	Payload Too Large	Request body exceeds the 150 MB Phoenix parser ceiling. Responses use code `10015` with detail “The request payload exceeds the maximum allowed size”.
422	Unprocessable Entity	Changeset validation error, message/body size limit exceeded, idempotency fingerprint conflict, or all recipients suppressed.
429	Too Many Requests	Account daily send limit exceeded, sender-domain warm-up ramp limit exceeded, or sending suspended due to poor domain reputation.
500	Internal Server Error	Unexpected server error.
503	Service Unavailable	Upstream dependency or Edge idempotency protection unavailable.

Error code reference

Every code in this section is a synchronous error — returned in the HTTP response to your API request. Delivery failures that happen after a 202 Accepted use the separate 30xxx taxonomy.

400 — Bad Request

Code	Title	Cause
`10015`	Bad Request / Validation Failed	Missing or invalid fields in the request body (e.g. `email is required`, `subject must be a non-empty string`).
`10015`	Invalid Idempotency-Key	The `Idempotency-Key` header is empty, duplicated, malformed, or exceeds the length limit. Generate a UUID v4 and pass it as a single header, not a body field.

401 — Unauthorized

Code	Title	Cause
`10006`	Not authorized	The `Authorization` header is missing or the API key is invalid, expired, or revoked.

403 — Forbidden

Code	Title	Cause
`10007`	Forbidden	Domain is not verified, suspended, degraded, or missing DKIM — or the `from` address is not authorized on the sending domain.
`10007`	Forbidden	The request requires the `email:override` scope (used to send to a suppressed recipient) and your API key does not have it.
`20012`	Account inactive	The account has been deactivated — commonly out of funds. This is a billing state, not a domain or permission problem. Resolve the account balance before retrying.
`10008`	Forbidden	Attempted to `PATCH`, `DELETE`, or `POST …/verify` on a shared domain you don’t own. Shared domains are read-only for non-owners. Owned by the email-domains service — see the caveat under Codes owned by other services.

404 — Not Found

Code	Title	Cause
`10001`	Not Found	Email message, template, or domain not found. Check the ID and your account scope. Both explicit application 404s and framework-level routing 404s return `10001` — there is no string `"404"` fallback code.

409 — Conflict

Code	Title	Cause
`10036`	Resource is being processed	A request with the same `Idempotency-Key` is still being processed. Retry later with the same key and the same request body.
`40901`	Conflict	Deleting an unsubscribe group that has active suppressions (without `?force=true`). Remove the suppressions first or pass `force=true`. Owned by the email-blocks service — see Codes owned by other services.

422 — Unprocessable Entity

Code	Title	Cause
`10015`	Validation Failed	Changeset validation error (e.g. `subject can't be blank`, invalid `webhook_url`, bad address format).
`10015`	Bad Request	Message size limit exceeded — 1 MB decoded body or 25 MB total message. See Request and message size limits.
`10027`	Idempotency Conflict	The `Idempotency-Key` was already used for a different request body. Use a new key for a new request; reuse keys only for exact retries.
`recipient_suppressed`	Recipient Suppressed	All recipients are suppressed — the email was not sent. The response includes a top-level `suppressed` array alongside `errors`, each entry carrying `to`, `reason`, `scope`, and `override_allowed`.

429 — Too Many Requests

Code	Title	Cause	Retry?
`10011`	Too Many Requests	The account’s daily send limit was exceeded. The detail names the limit and states that it resets at midnight UTC. The send is rejected before message creation — no message record, no billing, no MTA injection.	Yes, after the daily reset.
`domain_graduation_limit_exceeded`	Too Many Requests	The sender domain’s warm-up ramp daily recipient limit was exceeded — a per-domain volume cap on verified custom domains during warm-up, separate from the account quota. The send is rejected before message creation — no message record, no billing, no MTA injection. This is the only Email API `429` whose response carries the `Retry-After` header (seconds to the midnight UTC reset).	Yes — wait the `Retry-After` interval or resume after the daily reset, within the ramp’s per-day volume.
`reputation_suspended`	Sending Suspended	The sending domain’s reputation band is `poor` — sending is suspended until reputation recovers. Rejected before message creation.	No. See Deliverability.

domain_graduation_limit_exceeded example (the meta fields and the ramp stage in detail are present only when known — they are omitted, never null):

{
  "errors": [
    {
      "code": "domain_graduation_limit_exceeded",
      "title": "Too Many Requests",
      "detail": "Daily send limit of 250 recipients for this sender domain exceeded. The limit resets at midnight UTC.",
      "meta": {
        "retry_after_seconds": 3600,
        "remaining_today": 0
      }
    }
  ]
}

The account quota is checked before the domain ramp — a send rejected by the account quota returns 10011 without consulting the ramp at all. Both are recipient-count limits, so a send must fit both: whichever remaining headroom is lower is the binding constraint, and exceeding the domain’s is what returns domain_graduation_limit_exceeded. See Rate Limits & Quotas for the full ordering and counting rules.

Do not treat every 429 as a transient rate limit. Branch on the error code, not the status. 10011 clears on its own at midnight UTC. domain_graduation_limit_exceeded clears at the domain’s midnight UTC ramp reset — honor the Retry-After header, which only this 429 sets (10011 and reputation_suspended never do). reputation_suspended does not clear by waiting — retrying it in a backoff loop will never succeed and worsens the reputation signal. Stop sending on that domain and remediate the underlying bounce/complaint rates first.

Scheduled sends are never rejected with a 429 at fire time. A scheduled send bypasses admission when it is accepted and is evaluated against both the account quota and the sender-domain ramp when the scheduled worker fires. There is no HTTP request in flight then. A ramp rejection terminalizes recipients as failed with reason sender_domain_graduation_rejected; a fail-closed graduation dependency failure that exhausts its retries uses sender_domain_graduation_unavailable. Both store and publish recipient-scoped email.failed events, and normal rollup can leave the parent message completed. There is no synchronous HTTP error code for either path—detect them through recipient events or webhooks.

500 — Internal Server Error

Code	Title	Cause
`10019`	Internal Server Error	Unexpected server-side error (e.g. `Failed to create batch validation`). Retry with the same `Idempotency-Key`. If persistent, contact support.
`10000`	Internal Server Error	Returned by specific internal-failure paths, including a failed GDPR email-data deletion and email trace retrieval. Same handling as `10019`.
`500`	Internal Server Error	Framework fallback error response. Same handling as `10019`.

503 — Service Unavailable

Code	Title	Cause
`10016`	Service Unavailable	An upstream dependency (e.g. the email domain service) or Edge idempotency protection is temporarily unavailable. Retry with the same `Idempotency-Key`.

`error_evidence` structure

Failure events carry the normalized contract as error_evidence:

{
  "error_evidence": {
    "code": "30001",
    "message": "550 5.1.1 <user@example.com>: Recipient address rejected",
    "enhanced_code": "5.1.1",
    "source": "smtp",
    "smtp_status": 550,
    "retryable": false
  }
}

Field	Type	Description
`code`	string	The normalized 30xxx code from the table above. Never a raw SMTP status.
`message`	string \| null	The raw SMTP response text, when the failure reached SMTP.
`enhanced_code`	string \| null	DSN enhanced status code (e.g. `5.1.1`), when the remote supplied one.
`source`	string	Where the failure was observed: `smtp`, `mta`, or `api`.
`smtp_status`	integer \| null	The raw SMTP status as an integer. `null` for failures that never reached SMTP — queue expiry, suppression, and gateway rejection.
`retryable`	boolean	Whether resubmitting could succeed. Only `30002` is `true`.

The same normalized error is also published in array form as errors[], where each entry adds a human-readable title and renames message to detail. See Error evidence on failure events.

The webhook event type does not uniquely identify the failure. An ordinary bounce, a queue expiration, an administrative bounce, and an out-of-band bounce all publish email.bounced. Branch on error_evidence.code — for example 30001 versus 30005 — and read the recipient status for the authoritative outcome. bounce_category is an internal field: it is not part of normal recipient-scoped webhook payloads and is not written to normal recipient-scoped stored events. A legacy message-scoped fallback path may persist it in stored events, and the Events API sanitizer does not explicitly strip it. Do not build consumer logic that reads bounce_category from any public surface.

Idempotency-specific errors

When using the Idempotency-Key header, idempotency is enforced at the Telnyx Edge (API gateway) before the request reaches the Email API. The same key can produce three distinct outcomes, and they must be handled differently:

Outcome	HTTP	Code	What happened	Action
Original still in flight	409	`10036`	The first request with this key is still being processed. No second send occurred.	Wait and retry with the same key and the same body. Do not generate a new key — that would send twice.
Same key, different body	422	`10027`	The key was already used with a different request fingerprint. The new request was rejected without sending.	Generate a new key. Reuse a key only for byte-identical retries of the same logical request.
Original already completed	original 2xx	original body	The first request finished. The gateway replays its stored response verbatim — including the original status and body — and adds an `idempotent-replayed: true` response header.	Nothing. The message was sent exactly once. Check for the `idempotent-replayed` header if you need to distinguish a replay from a fresh send.

Two further failure modes are specific to the idempotency layer itself:

Code	HTTP	Cause	Action
`10015`	400	Malformed key (empty, duplicate header, overlong)	Generate a valid UUID v4 and pass it as a single `Idempotency-Key` header.
`10016`	503	Idempotency protection unavailable (fail-closed)	Retry the same request with the same key. The gateway fails closed rather than risking a duplicate send.

A replay only works while the gateway holds the stored response. Requests whose body exceeds the Edge replay cap — 8 MB for single sends, 20 MB for batches — are rejected at the Edge with 413 Payload Too Large before reaching the Email API — see Request and message size limits.

Batch-specific errors

Batch requests (POST /email_messages/batch, up to 1,000 messages) return 207 Multi-Status for every processed batch — including an all-success batch, where errors is empty — with per-message errors:

{
  "data": [/* successful messages */],
  "errors": [
    {
      "index": 1,
      "code": "forbidden",
      "message": "Domain is not verified"
    }
  ],
  "meta": {
    "total": 2,
    "failed": 1,
    "succeeded": 1
  }
}

Each batch error entry has index (position in your messages array), code, and message:

Error code	Cause
`bad_request`	Malformed message entry, missing required fields, a template render error, or a field validation failure for that message.
`validation_error`	Field validation failed for that message.
`unprocessable_entity`	That message exceeded a size limit — either the 1 MB decoded body or the 25 MB total message ceiling. Note this is a per-message failure: the rest of the batch still processes. See Request and message size limits.
`forbidden`	Domain not verified or from-address not allowed.
`not_found`	Template ID or domain not found (for template sends).
`recipient_suppressed`	All recipients of that message are suppressed.
`reputation_suspended`	Sending suspended for the domain’s reputation band.
`service_unavailable`	Upstream dependency unavailable for that message.

Codes owned by other services

The Telnyx email product spans several services. A few codes documented here are returned by services other than the Email API, which means their exact status, code, and detail can change independently of this page. Verify these against the owning service’s API reference before depending on the precise shape:

Area	Owning service	Notes
Shared-domain mutation (`10008`)	telnyx-email-domains	Returned as `403 Forbidden` when mutating a shared domain you don’t own.
Unsubscribe-group deletion conflict (`40901`)	email-blocks	Returned by the suppressions/unsubscribe-group surface.
`/v2/email_domains` troubleshooting and domain verification errors	telnyx-email-domains	Domain registration, DNS record generation, verification, and drift monitoring all live in the domains service.
Webhook CRUD (`/email_domains/{domain_id}/webhooks`)	telnyx-email-domains	The Email API only resolves webhook targets at publish time; it does not serve these routes.

Error codes are not globally unique across Telnyx email services. 10008 is the clearest example: the email-domains service returns it as a 403 Forbidden for shared-domain mutation, while the Email API returns the same code as a 503 Service Unavailable when diagnostics authentication is unavailable. Always interpret a code together with both the HTTP status and the endpoint that returned it — never on the code alone.

Troubleshooting

”Domain is not verified”

Check GET /v2/email_domains to see the domain status.
Ensure all required DNS records — ownership and DKIM, plus MX if inbound_enabled is true — are published and match the records returned by GET /v2/email_domains/{domain_id}/dns_records.
Call POST /v2/email_domains/{domain_id}/verify after DNS propagates.
For a controlled zero-setup test, use onboarding@<shared-domain> and send only to the account owner’s verified email address.

”sender address is not allowed”

The from address must be on a verified domain you own. Shared-domain sends must use onboarding@<shared-domain> and can target only the account owner’s verified email address.

”Idempotency-Key header is invalid”

Generate a UUID v4 (uuidgen or crypto.randomUUID()).
Pass it as an HTTP header: Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9326.
Do not include it in the JSON body — it’s a header only.
One key per logical request. Reuse only for exact retries.

Sending suspended (`reputation_suspended`)

Your domain’s reputation band dropped to poor — usually from high bounce or complaint rates. See Deliverability and Domain Warm-up for recovery guidance.

Sender-domain ramp rejection (`domain_graduation_limit_exceeded`)

Your sending domain is still in warm-up and the send would have exceeded the domain’s daily recipient allowance for the current ramp stage. This is a volume cap, not a reputation or account-quota problem:

Honor the Retry-After response header — it holds the seconds until the domain’s midnight UTC reset. The error meta may also carry retry_after_seconds and remaining_today (omitted when unknown).
Check whether sibling subdomains share the ramp — the allowance is per registrable organizational domain, so mail across mail.example.com and news.example.com draws from one daily cap.
Spread the remaining volume: submit fewer recipients per day, or queue and resume after the UTC reset.
If the ramp stage is not advancing as expected, see Deliverability and Domain Warm-up — a reputation warning pauses advancement without lowering the current cap.

If you see recipient failed events with reason sender_domain_graduation_rejected instead of a 429, a scheduled send exceeded the ramp at fire time. Reason sender_domain_graduation_unavailable means a fail-closed graduation dependency failure exhausted its scheduled-worker retries. Neither has a synchronous HTTP code; see Rate Limits & Quotas.

Choosing a retry strategy

Retry decisions belong on the error code, not the HTTP status. Two errors that share a status can need opposite handling.

Error	Status	Retry?	How
`10011` (daily send limit)	429	Yes	The limit resets at midnight UTC. Queue the work locally and resume after the reset — backing off in seconds will not help.
`domain_graduation_limit_exceeded` (sender-domain ramp)	429	Yes	Wait the `Retry-After` interval (seconds to the domain’s midnight UTC reset) and stay within the ramp’s remaining per-day volume. The counter is daily, so backoff over seconds alone will not clear it.
`reputation_suspended`	429	No	Waiting does not clear it. Stop sending on that domain, reduce bounce and complaint rates, then confirm the band recovered.
`10036` (idempotency in flight)	409	Yes	Retry with the same key and body. A new key would send a duplicate.
`10027` (idempotency fingerprint)	422	No	The body differs from the original. Fix the body or use a new key.
`10016` (service unavailable)	503	Yes	Retry the same request with the same `Idempotency-Key`, with exponential backoff.
`10019` / `10000` / `500`	500	Yes	Retry with the same `Idempotency-Key`. Contact support if persistent.
`10015` (validation / size)	400, 413, 422	No	The request is malformed or too large. Retrying it unchanged always fails.
`10007` / `20012` (forbidden / inactive)	403	No	Fix domain verification, sender authorization, scope, or account balance first.
`recipient_suppressed`	422	No	Every recipient is suppressed. Remove them or send to different addresses.

Never retry a 4xx other than 409 and 429 without changing the request — the outcome is deterministic. And when you do retry a send, always reuse the original Idempotency-Key so a retry that races a slow success cannot deliver the message twice.

Delivery failed after a `202 Accepted`

A 202 only confirms acceptance for sending. If the message never arrived, the failure is asynchronous — look at the 30xxx delivery error on the recipient’s webhook or event, not at the HTTP response. Start with error_evidence.code:

30001 — permanent rejection. Remove the address.
30002 — temporary; Telnyx is already retrying. Do not resubmit.
30004 — the recipient was suppressed before any attempt.
30005 — retries were exhausted; the recipient status is expired.

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

For AI Agents

Error response format

Request and message size limits

HTTP status codes

Error code reference

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable Entity

429 — Too Many Requests

500 — Internal Server Error

503 — Service Unavailable

`error_evidence` structure

Idempotency-specific errors

Batch-specific errors

Codes owned by other services

Troubleshooting

”Domain is not verified”

”sender address is not allowed”

”Idempotency-Key header is invalid”

Sending suspended (`reputation_suspended`)

Sender-domain ramp rejection (`domain_graduation_limit_exceeded`)

Choosing a retry strategy

Delivery failed after a `202 Accepted`

​Error response format

​Request and message size limits

​HTTP status codes

​Error code reference

​400 — Bad Request

​401 — Unauthorized

​403 — Forbidden

​404 — Not Found

​409 — Conflict

​422 — Unprocessable Entity

​429 — Too Many Requests

​500 — Internal Server Error

​503 — Service Unavailable

​error_evidence structure

​Idempotency-specific errors

​Batch-specific errors

​Codes owned by other services

​Troubleshooting

​”Domain is not verified”

​”sender address is not allowed”

​”Idempotency-Key header is invalid”

​Sending suspended (reputation_suspended)

​Sender-domain ramp rejection (domain_graduation_limit_exceeded)

​Choosing a retry strategy

​Delivery failed after a 202 Accepted

Error response format

Request and message size limits

HTTP status codes

Error code reference

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable Entity

429 — Too Many Requests

500 — Internal Server Error

503 — Service Unavailable

`error_evidence` structure

Idempotency-specific errors

Batch-specific errors

Codes owned by other services

Troubleshooting

”Domain is not verified”

”sender address is not allowed”

”Idempotency-Key header is invalid”

Sending suspended (`reputation_suspended`)

Sender-domain ramp rejection (`domain_graduation_limit_exceeded`)

Choosing a retry strategy

Delivery failed after a `202 Accepted`