Email API error code reference

Look up the error codes the Email API returns, tell whether the fault is in your request or on our side, and know which codes are worth retrying.

Look up the code you received. To start from a symptom instead, see Email API troubleshooting.

Every error response has the same shape, and message is the code you look up below:

{ "success": false, "statusCode": 403, "message": "DOMAIN_NOT_VERIFIED" }

HTTP status groups

Read the first digit before the detailed code — it decides whether retrying makes sense.

Status	Meaning	Retry?
`202`	Accepted and queued. Keep the `id` to look it up later	—
`400`	Bad request — a field is missing or malformed	No, fix the request first
`401`	Key is wrong or revoked, or the call comes from an IP outside the key's IP restrictions	No
`403`	Key is valid but not allowed to do this	No
`404`	The `id` or address was not found	No
`410`	The content retention window has expired	No
`413`	Message exceeds the size ceiling	No, reduce the size
`422`	Valid request that cannot be processed — recipient on your suppression list (`RECIPIENT_SUPPRESSED`) or verified as non-existent (`RECIPIENT_PLATFORM_SUPPRESSED`)	No
`429`	Quota or rate limit exceeded	Yes, wait and send again
`500`	Fault on our side	Yes, with increasing delays
`503`	Infrastructure temporarily unavailable	Yes, with increasing delays

Short version: 4xx means the request is wrong, except 429. Only 429, 500 and 503 are worth retrying — retrying a 400 returns the same 400 forever.

Recipient and content errors

This whole group happens before quota is charged. A rejected message does not count against your daily or cycle allowance.

Code	HTTP	When you get it
`INVALID_TO`	400	The `to` list is empty after duplicates are removed
`INVALID_RECIPIENT`	400	An address in `to`, `cc` or `bcc` is malformed
`TOO_MANY_RECIPIENTS`	400	`to` + `cc` + `bcc` exceeds 50 addresses
`CONTENT_REQUIRED`	400	Both `html` and `text` are missing. With a template, this means the template produced nothing
`VALIDATION_ERROR`	400	The request is structurally wrong. The response carries an `errors` field pointing at the offending field

Duplicate addresses are merged before counting, so sending to the same address twice does not push you over the limit sooner.

Attachment errors

Code	HTTP	When you get it
`INVALID_ATTACHMENT`	400	The `content` field is not valid base64
`TOO_MANY_ATTACHMENTS`	400	More than 10 files in one message
`INVALID_FILENAME`	400	The filename is empty, is `.` or `..`, or exceeds 255 bytes
`ATTACHMENT_TYPE_BANNED`	400	The extension is on the blocked list — `.exe`, `.bat`, `.cmd`, `.js`, `.vbs`, `.scr`, `.pif` and many other executable types
`MESSAGE_TOO_LARGE`	413	The message exceeds the 25 MB ceiling. The response carries `limitBytes` and `actualBytes` so you can see by how much
`ATTACHMENT_EXPIRED`	410	Fetching an attachment after the content retention window closed

Directory paths in a filename are not rejected — the system trims to the base name first and then checks the length.

The blocked list matches on the extension, not on the file contents. To send one of these, put it in an archive, or host it for download and send a link.

Code	HTTP	When you get it
`DOMAIN_NOT_VERIFIED`	403	The domain in `from` is not active, does not exist, or belongs to a different service
`DOMAIN_SCOPE_VIOLATION`	403	The sending key is bound to a domain other than the one in `from`
`SENDING_KEY_REQUIRED`	403	An Account Key was used to send mail. Sending only accepts a Sending Key
`ACCOUNT_KEY_REQUIRED`	403	A sending key was used for an account management call. The two key types are not interchangeable
`ACCOUNT_SUSPENDED`	403	The service account is suspended
`COMPLAINT_SUPPRESSION_LOCKED`	403	The address reached the suppression list through a spam complaint. You cannot remove it yourself — contact support
`BOUNCE_SUPPRESSION_LOCKED`	403	The address reached the suppression list because the receiver said it does not exist. You cannot remove it yourself — contact support

DOMAIN_NOT_VERIFIED is returned identically in three cases: the domain does not exist, the domain has not finished verification, and the domain belongs to a different service. That is deliberate — distinct answers would let outsiders probe which domains exist on the platform. Check the real status on the Sending domains screen.

Quota and system errors

Code	HTTP	When you get it	What to do
`429`	429	Daily or 30-day cycle quota exhausted, or too many messages in a short burst	See below
`QUOTA_BACKEND_UNAVAILABLE`	503	The quota counter is temporarily unreachable	Wait and send again
`ENQUEUE_FAILED`	503	The message could not be queued	Wait and send again
`ATTACHMENT_UPLOAD_FAILED`	503	Storing an attachment failed. No message was created and the quota was refunded	Send again
`ATTACHMENT_STORAGE_UNAVAILABLE`	503	Attachment storage is temporarily unavailable	Wait and send again

429 has two causes whose fixes are opposites:

Rate limit — wait a few seconds and send again. Your remaining daily allowance is unchanged.
Daily quota exhausted — retrying returns 429 until midnight no matter how often you try. Compare the sent count on the Overview screen to tell which one you are hitting.

Your account's real quota is in the Email API account quota block on the Overview screen — see Read the overview page of each service. The per-message technical ceilings are under Limits & errors in Email API → Guide in the console.

Retrying properly

For 429, 500 and 503, increase the delay between attempts instead of resending immediately: 1 second, 2 seconds, 4 seconds, 8 seconds. Retrying in a tight loop is the fastest way to lock yourself out.

Cap the number of attempts. After five failures, record the request and contact support rather than retrying forever.

A 202 means the message is queued only. The delivery outcome arrives later, on the Stats & logs screen or through a webhook.