API error codes
Every code has a stable link. Put the code after the hash, like /docs/errors#rate_limited, and it lands on the right entry.
Envello errors
Send, template and domain-claim errors carry a snake_case error code and a readable message. Branch on the code, never the message.
HTTP/1.1 403 Forbidden
{
"error": "domain_not_verified",
"message": "..."
}Plain HTTP errors
Management endpoints (domains, logs, suppressions, webhooks, inbound) return the HTTP status name in error plus a statusCode. A 401 means the key is missing or invalid, a 403 that this key can't use the endpoint. The API reference lists which key each endpoint needs.
HTTP/1.1 403 Forbidden
{
"statusCode": 403,
"error": "Forbidden",
"message": "Test keys can't manage live resources. ..."
}missing_api_keyHTTP 401
The request has no Authorization: Bearer <key> header.
Fix: Send your API key as a bearer token. Keys start with env_live_ or env_test_.
invalid_api_keyHTTP 401
The key is malformed, revoked, or belongs to a suspended account.
Fix: Copy the key again from the dashboard, or create a new one. A rotated key stops working immediately.
live_mode_requires_verificationHTTP 403
A live-mode key was used before the account email was verified.
Fix: Click the link in the verification email. Test-mode keys work before verification.
insufficient_key_permissionHTTP 403
A sending_access key called an endpoint that needs a full_access key.
Fix: Use a full-access key for management endpoints. Sending keys can only send and read their own sends.
key_domain_restrictedHTTP 403
The key is locked to one sending domain and the from address uses another.
Fix: Send from the domain the key is locked to, or use a key without a domain restriction.
invalid_requestHTTP 400
The body failed validation. The response has an issues array naming each bad field.
Fix: Fix the fields listed in issues. The API reference lists every field and its limits.
invalid_idHTTP 400
The id in the URL is not a valid UUID.
Fix: Use the id returned when the resource was created.
not_foundHTTP 404
No resource with that id exists on this account.
Fix: Check the id and that the key belongs to the same account that created it.
invalid_idempotency_keyHTTP 400
The Idempotency-Key header is too long or has characters outside letters, digits, ., _, : and -.
Fix: Use a UUID or another short value from that character set.
idempotency_key_conflictHTTP 409
The Idempotency-Key was already used with a different request body.
Fix: Use a new key for a new request. Reuse a key only to retry the exact same request.
attachment_too_largeHTTP 413
An attachment, or all attachments together, are over the size limit.
Fix: Shrink or drop attachments, or link to the file instead.
domain_not_verifiedHTTP 403
The from domain is not a verified sending domain on this account.
Fix: Add the domain in the dashboard or with POST /domains, publish its DNS records, then verify it.
onboarding_sender_restrictedHTTP 403
A send from the shared onboarding address went to someone other than the account's own email.
Fix: The onboarding address can only mail your own verified address. Verify a domain to send to anyone else.
account_pausedHTTP 403
Sending is paused on this account, usually because bounce or complaint rates passed the safety threshold.
Fix: Email [email protected] to have the account reviewed. The message field says why it paused.
account_held_for_reviewHTTP 403
The account is held for a manual review before it can send.
Fix: Email [email protected] to have the account activated.
broadcast_pausedHTTP 403
The broadcast stream is paused for this account. Transactional sending still works.
Fix: Email [email protected] to have the broadcast stream reviewed.
broadcast_stream_disabledHTTP 403
stream: "broadcast" was sent but the broadcast stream isn't enabled for this account.
Fix: Send as transactional, or ask for the broadcast stream to be enabled.
broadcast_stream_not_enabledHTTP 403
stream: "broadcast" was sent but no admin has switched the broadcast stream on for this account.
Fix: An admin can switch it on in the dashboard under Settings > Broadcast stream. Transactional sending isn't affected.
invalid_broadcast_requestHTTP 400
A broadcast email must have exactly one to recipient and no cc or bcc, so each message can carry its own unsubscribe link.
Fix: Send one broadcast email per recipient. Use POST /emails/batch for many.
verification_fee_requiredHTTP 402
The account hasn't paid the one-time sender verification fee, so production sending is locked.
Fix: Pay it in the dashboard under Billing. Test-mode keys keep working in the meantime.
monthly_spend_cap_reachedHTTP 429
The account's spend cap is on and this billing period's plan quota is used up, so sending stops instead of billing overage.
Fix: Wait for the next billing period, or have an admin turn the cap off or upgrade under Billing. Test-mode keys keep working.
reputation_throttledHTTP 429
The account's bounce or complaint rate is high, so production sending is throttled to a per-minute and per-day recipient budget. The response has limit, daily_limit and retry_after_seconds, plus a Retry-After header.
Fix: Wait retry_after_seconds and retry. Clean your list; the throttle lifts automatically once the rate is back down.
rate_limitedHTTP 429
Too many send requests from this key in a short window.
Fix: Back off and retry. Use POST /emails/batch to send many emails in one request.
daily_send_cap_exceededHTTP 429
The account reached its daily sending limit. New accounts start low and the limit rises as reputation builds.
Fix: Retry tomorrow, or email [email protected] if you need a higher limit sooner.
recipient_suppressedHTTP 422
One or more recipients are on the suppression list after a bounce, complaint or unsubscribe. The response has suppressed_count.
Fix: Remove them from the send, or delete the suppression with DELETE /suppressions/{email} if you know the address is good again.
recipient_domain_invalidHTTP 422
A recipient's domain has no MX record, publishes a null MX, doesn't exist, or is a known typo domain such as gmail.co.
Fix: Check the address for typos.
content_blockedHTTP 422
The content matched patterns commonly associated with spam or phishing.
Fix: Review links and wording. Email [email protected] if you think the block is wrong.
template_not_foundHTTP 404
template_id doesn't match a template on this account.
Fix: List templates with GET /templates and use one of their ids.
template_variables_missingHTTP 422
The template declares variables the request didn't provide. The response lists them in variables.
Fix: Pass every declared variable in variables.
template_variables_unknownHTTP 422
The request passed variables the template doesn't declare. The response lists them in variables.
Fix: Remove them, or add them to the template's variables.
template_placeholder_undeclaredHTTP 422
The template body uses a placeholder that isn't in its variables list.
Fix: Add the placeholder to the template's variables with PUT /templates/{id}.
send_at_in_pastHTTP 422
send_at is not in the future.
Fix: Use a future ISO 8601 timestamp, or omit send_at to send now.
not_reschedulableHTTP 409
The email isn't scheduled, so there's nothing to move.
Fix: Only emails sent with send_at that haven't fired can be rescheduled.
not_cancelableHTTP 409
The email isn't scheduled, so there's nothing to cancel.
Fix: Only emails sent with send_at that haven't fired can be canceled.
already_sendingHTTP 409
The scheduled send already started, so it can't be moved or canceled.
Fix: None. The email is on its way.
claim_record_not_foundHTTP 422
The TXT record for a domain claim isn't visible in DNS yet.
Fix: Publish the TXT record from the message, wait for DNS to propagate, then call POST /domains/claim/verify again.