Envello
Docs

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.

broadcast_unavailableHTTP 503

Broadcast sending isn't configured on this server yet.

Fix: Send as transactional for now.

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.

not_shareableHTTP 409

A canceled email has nothing to share.

Fix: Share links work for sent and scheduled emails only.

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.