Errors
Errors come back as JSON with an HTTP status, a stable code for your code to check, and a message written for people.
{
"error": {
"code": "recipient_suppressed",
"message": "Not sent: old@example.com bounced or complained before. Remove them from the suppression list to send again."
}
}Check code, not message. Messages can change wording; codes don't.
Codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON, or a field has the wrong type. |
| 401 | missing_api_key | No Authorization: Bearer zv_… header. |
| 401 | invalid_api_key | The key doesn't exist or was deleted. |
| 403 | insufficient_scope | A send-only key was used for an endpoint that needs full access. |
| 403 | account_paused | Sending is paused, usually because of a high bounce or complaint rate. The message says why. |
| 403 | account_suspended | The account is suspended. Contact support. |
| 403 | email_not_confirmed | The account sent its 50 emails allowed before the email address is confirmed. Open the confirmation link, or send a new one from the dashboard. |
| 403 | domain_not_found | The from domain isn't in your account. |
| 403 | domain_not_verified | The from domain isn't verified yet. |
| 403 | from_not_allowed | The from address can't be used for sending. |
| 400 | invalid_idempotency_key | The Idempotency-Key header is longer than 256 characters. |
| 400 | invalid_domain | The domain name isn't valid, or is one of Zevuki's own. |
| 403 | plan_limit | Your plan's domain or mailbox limit is reached. |
| 404 | not_found | No email or domain with this ID in your account. |
| 409 | domain_taken | The domain is already added, by you or another account. |
| 409 | domain_in_use | The domain still has mailboxes, or emails from it are still being sent. |
| 409 | domain_send_only | Mailboxes need a domain that receives mail. Turn on receiving first. |
| 409 | not_scheduled | The email can't be moved or canceled: it was already sent, canceled or failed. |
| 422 | invalid_attachment | An attachment is missing its filename or content, isn't base64, or uses path. |
| 422 | attachments_too_large | Attachments add up to more than 10 MB. |
| 422 | invalid_scheduled_at | scheduled_at isn't a future time within 30 days, or was used in a batch. |
| 422 | invalid_tags | More than 10 tags, or a tag name with characters other than letters, digits, _ and -. |
| 422 | invalid_batch | A batch must have 1 to 100 emails. |
| 422 | invalid_endpoint | A webhook endpoint must be a public https:// URL. |
| 422 | invalid_events | Unknown webhook event name. |
| 409 | invalid_idempotent_request | The Idempotency-Key was already used with a different request body. |
| 409 | concurrent_idempotent_requests | A request with the same Idempotency-Key is still being processed. Retry shortly. |
| 422 | invalid_from | from isn't a valid address. |
| 422 | invalid_to, invalid_cc, invalid_bcc, invalid_reply_to | An address in that field isn't valid. |
| 422 | missing_to | to is empty. |
| 422 | too_many_recipients | More than 50 addresses in to, cc and bcc together. |
| 422 | missing_subject | subject is empty. |
| 422 | missing_body | Neither html nor text was given. |
| 422 | recipient_suppressed | A recipient bounced or complained before. Nothing was sent. Remove the address from the blocked list in the dashboard if it's fixed. |
| 422 | send_rejected | The mail server refused the message, for example because a daily sending limit was reached. The message says why. |
| 429 | monthly_limit_reached | This month's emails are used up. On Free, subscribe to Starter or Pro. On a paid plan, buy a top-up or turn on auto top-up. |
| 429 | rate_limit_exceeded | More than 10 requests a second with this API key. Wait for the Retry-After seconds and retry. |
| 429 | rate_limited | Too many requests in a short time. Wait and retry. |
| 500 | server_error | Something failed on our side. Retry with backoff; if it keeps happening, contact support. |
When to retry
Retry 429 rate_limited and 5xx errors with exponential backoff (for example after 1, 2, 4 and 8 seconds). Don't retry 4xx errors without changing the request: they fail the same way every time.