zevuki mailbox

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 shape
{
  "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

StatusCodeMeaning
400invalid_jsonThe body isn't valid JSON, or a field has the wrong type.
401missing_api_keyNo Authorization: Bearer zv_… header.
401invalid_api_keyThe key doesn't exist or was deleted.
403insufficient_scopeA send-only key was used for an endpoint that needs full access.
403account_pausedSending is paused, usually because of a high bounce or complaint rate. The message says why.
403account_suspendedThe account is suspended. Contact support.
403email_not_confirmedThe account sent its 50 emails allowed before the email address is confirmed. Open the confirmation link, or send a new one from the dashboard.
403domain_not_foundThe from domain isn't in your account.
403domain_not_verifiedThe from domain isn't verified yet.
403from_not_allowedThe from address can't be used for sending.
400invalid_idempotency_keyThe Idempotency-Key header is longer than 256 characters.
400invalid_domainThe domain name isn't valid, or is one of Zevuki's own.
403plan_limitYour plan's domain or mailbox limit is reached.
404not_foundNo email or domain with this ID in your account.
409domain_takenThe domain is already added, by you or another account.
409domain_in_useThe domain still has mailboxes, or emails from it are still being sent.
409domain_send_onlyMailboxes need a domain that receives mail. Turn on receiving first.
409not_scheduledThe email can't be moved or canceled: it was already sent, canceled or failed.
422invalid_attachmentAn attachment is missing its filename or content, isn't base64, or uses path.
422attachments_too_largeAttachments add up to more than 10 MB.
422invalid_scheduled_atscheduled_at isn't a future time within 30 days, or was used in a batch.
422invalid_tagsMore than 10 tags, or a tag name with characters other than letters, digits, _ and -.
422invalid_batchA batch must have 1 to 100 emails.
422invalid_endpointA webhook endpoint must be a public https:// URL.
422invalid_eventsUnknown webhook event name.
409invalid_idempotent_requestThe Idempotency-Key was already used with a different request body.
409concurrent_idempotent_requestsA request with the same Idempotency-Key is still being processed. Retry shortly.
422invalid_fromfrom isn't a valid address.
422invalid_to, invalid_cc, invalid_bcc, invalid_reply_toAn address in that field isn't valid.
422missing_toto is empty.
422too_many_recipientsMore than 50 addresses in to, cc and bcc together.
422missing_subjectsubject is empty.
422missing_bodyNeither html nor text was given.
422recipient_suppressedA recipient bounced or complained before. Nothing was sent. Remove the address from the blocked list in the dashboard if it's fixed.
422send_rejectedThe mail server refused the message, for example because a daily sending limit was reached. The message says why.
429monthly_limit_reachedThis 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.
429rate_limit_exceededMore than 10 requests a second with this API key. Wait for the Retry-After seconds and retry.
429rate_limitedToo many requests in a short time. Wait and retry.
500server_errorSomething 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.