Error Codes

All API errors return a consistent JSON format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "details": {}
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

Use the request_id when contacting support.

Authentication Errors

Code	HTTP Status	Description	Resolution
unauthorized	401	Missing or invalid API key	Check your X-API-Key header
forbidden	403	API key lacks required permissions	Use a key with appropriate scopes
ip_not_allowed	403	Request from non-allowlisted IP	Add the IP to your key's allowlist in Settings
account_locked	403	Account is locked	Contact support@zyphr.dev
account_suspended	403	Account suspended for policy violation	Contact support@zyphr.dev
account_inactive	403	The account is not active. On end-user sign-in (passkey, OAuth, magic link, gaming, anonymous, MFA completion, password change, account conversion), the end user is suspended, usually by your application	If you suspended them, re-activate the end user (PATCH /v1/auth/users/:id with status: "active"). If you didn't, or for your own Zyphr account, contact support@zyphr.dev
invalid_token	401	The bearer/session token is invalid	Re-authenticate to obtain a fresh token
token_expired	401	The token has expired	Refresh the token or re-authenticate
key_revoked	401	The API key has been revoked	Create a new API key in Settings → API Keys
email_not_verified	403	The account/user email must be verified for this operation	Verify the email address, then retry
geo_restricted	403	The request originates from a restricted region	Contact support if you believe this is in error

Validation Errors

Code	HTTP Status	Description	Resolution
validation_error	400	Request body failed validation	Check details for specific field errors
invalid_url	400	Malformed URL provided	Ensure valid URL format
invalid_body	400	Request body shape is invalid	Check the request schema
invalid_params	400	Invalid query or path parameters	Check the parameter values
invalid_provider	400	The specified provider is not a supported/valid provider for this operation	Use a supported provider value
bad_request	400	The request is malformed or missing required context	Check the request against the endpoint's documentation
wrong_endpoint	400	The credential/request was sent to the wrong endpoint (e.g. an end-user token on an account endpoint)	Use the endpoint that matches your credential type

Rate Limiting

Code	HTTP Status	Description	Resolution
rate_limit_exceeded	429	Too many API requests	Back off and retry after retry_after seconds
otp_send_rate_limit_exceeded	429	Too many OTP/MFA code requests	Wait before requesting another code
otp_verify_rate_limit_exceeded	429	Too many OTP verification attempts	Wait before retrying
sms_send_rate_limit_exceeded	429	Too many SMS sends for this number (direct SMS-send API)	Wait before retrying
rate_limited	429	Too many login attempts for this identifier	Wait before retrying
quota_exceeded	429	Monthly send / MAU quota reached	Upgrade your plan or wait for the quota to reset
usage_limit_exceeded	429	The monthly Webhooks-as-a-Service event limit for your plan is reached (POST /v1/waas/applications/{appId}/events). A batch publish still returns 201; each event over the limit is listed in results with code: "usage_limit_exceeded"	Upgrade your plan or wait for the monthly reset
mau_quota_exceeded	402	An end-user sign-in would add a new monthly active user to an account already at its MAU limit. Users already counted this month can still sign in. The body includes limit and current	Upgrade your plan, or wait for the monthly reset
batch_exceeds_limit	429	The batch request exceeds the per-request recipient/item cap	Split into smaller batches
daily_limit_exceeded	429	The channel's daily send limit for your plan is reached (push)	Wait for the daily reset or upgrade your plan
sms_daily_limit_reached	429	The daily SMS send limit for your plan is reached	Wait for the daily reset or upgrade your plan
sms_limit_reached	429	The SMS send limit for your plan is reached	Upgrade your plan or wait for the reset
session_limit_exceeded	403	The end user has reached the application's max_concurrent_sessions and the application refuses new sessions (deny_new). Returned by sign-ins that open a session for an existing user (password, phone/email OTP, passkey, OAuth, magic link, gaming, MFA). Anonymous sign-in, registration and account conversion don't apply the limit. For MFA logins it is normally returned before a challenge is issued, so no TOTP or backup code is spent. It can still be returned at MFA completion if the user reached the limit after the challenge was issued. The body includes max_sessions and current_sessions	Revoke an existing session, raise the limit, or switch the app to revoke_oldest
test_environment_limit	403	Creating this end user would exceed the test environment's user limit	Delete test users or use the live environment
free_account_limit_reached	403	The per-user free-account cap has been reached	Upgrade a plan, or use an existing account

Account-level send throttle/freeze (reputation) has its own codes — see Sending Status (Reputation) Errors below.

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Sending Status (Reputation) Errors

When your account's sending reputation degrades (high bounce or complaint rate, or a sudden volume spike), Zyphr throttles or freezes sending to protect the shared IP pool. These states apply only to send-capable endpoints — read, billing, and deliverability endpoints stay available so you can diagnose and recover.

Code	HTTP Status	Description	Resolution
account_frozen	403	Sending is frozen for the account (reputation). The error message carries the specific reason.	Stop sending to invalid addresses, clean your recipient list, then contact support@zyphr.dev to unfreeze.
account_throttled	429	A percentage of sends are rejected while reputation recovers. The error message carries the reason.	Back off and retry; reduce bounce/complaint rates. Throttling lifts automatically once rates return to acceptable levels.

Every authenticated response includes the current sending state as headers, so you can surface it without a separate call:

X-Account-Sending-Status: frozen
X-Account-Sending-Status-Reason: Bounce rate (12.50%) exceeded freeze threshold (10%)

X-Account-Sending-Status is one of active, throttled, or frozen. X-Account-Sending-Status-Reason is present only when the status is not active. See API Limits for details.

Not Found Errors

Code	HTTP Status	Description	Resolution
not_found	404	Requested resource doesn't exist	Check the resource ID
user_not_found	404	User doesn't exist (e.g. on MFA endpoints; also returned as 401 if the user disappears mid-MFA-challenge)	Verify the user ID
template_not_found	404	Template ID doesn't exist	Verify the template_id
subscriber_not_found	404	Subscriber doesn't exist	Create the subscriber first
device_not_found	404	Device ID doesn't exist	Check device registration
topic_not_found	404	Topic doesn't exist	Create the topic first
account_not_found	404	Account doesn't exist	Verify the account context
organization_not_found	404	End-user organization doesn't exist	Verify the organization ID
environment_not_found	404	Environment (test/live) doesn't exist	Verify the environment

Webhook 404s return the generic not_found code (with a "Webhook not found" message), not a webhook_not_found code.

Conflict Errors

Code	HTTP Status	Description	Resolution
conflict	409	Resource already exists	Use update instead of create
domain_registered_elsewhere	409	Domain is claimed by another account	Use a different domain or contact support
already_verified	400	Domain/email is already verified	No action needed
duplicate_provider	409	An identity/OAuth provider of this type is already configured on the application	Update the existing provider instead of adding a new one
duplicate_connection	409	The end user already has a connection for this provider	No action needed — the connection exists
subscription_exists	400	A subscription already exists for this account	Manage the existing subscription instead
step_key_exists	409	A workflow step with this step_key already exists	Use a unique step_key

Configuration Errors

Code	HTTP Status	Description	Resolution
sms_not_configured	400 / 503	Twilio credentials not set up. 400 on the direct SMS-send API; 503 on the auth phone-OTP endpoints (see Auth OTP Errors).	Configure Twilio in Settings > SMS
domain_not_verified	400 / 422	Sending domain not verified (status is route-dependent)	Verify domain in Settings > Domains
no_verified_domain	422	No verified sending domain on the project	Add and verify a domain in Settings > Domains
domain_blocked	403	The sending domain is blocklisted	Contact support
not_configured	501	The requested feature/provider is not configured	Enable/configure it in Settings

MFA & Security Errors

Code	HTTP Status	Description	Resolution
mfa_required	—	MFA verification needed. Not an error — the login/verify endpoints return this as a 200 response body flag ({ "data": { "mfa_required": true, "mfa_challenge": { … } } }), not an error status. Branch on the mfa_required field.	Complete the MFA challenge with the returned mfa_challenge.token
otp_invalid	400	OTP code is incorrect	Enter the correct code
otp_expired	400	OTP code has expired	Request a new code
otp_max_attempts	400	Too many failed attempts on this code — it is now locked	Request a new code
invalid_totp	401	TOTP code is incorrect	Enter the current code from the authenticator app
invalid_backup_code	401	Backup code is invalid or already used	Use an unused backup code, or re-verify with TOTP
invalid_mfa	401	MFA challenge is invalid or expired	Restart the MFA challenge
invalid_verification	401	Verification code is incorrect (TOTP re-verification of an active session)	Re-enter the current code
invalid_code	400	Verification code is incorrect (during MFA enrollment)	Re-enter the code from the authenticator app
mfa_not_enabled	400	MFA is not enabled for this account	Enroll in MFA first
mfa_already_enabled	409	MFA is already enabled	No action needed
no_pending_enrollment	400	No MFA enrollment is in progress to verify	Start enrollment before verifying
email_required	400	The account must have an email address to enable MFA	Add an email to the account first

Branch on code, not message

Every error response includes a stable, machine-readable error.code alongside the human-readable error.message. Branch your control flow on error.code (and the HTTP status) — treat message as display-only text that may be reworded or localized at any time.

Auth OTP Errors (Email & Phone)

Returned by the email-OTP (/auth/email-otp/*) and phone-OTP (/auth/phone/*) send/verify endpoints.

Code	HTTP Status	Description	Resolution
email_not_found	400	No account exists for this email (on login send/verify)	Fall back to a registration flow, or prompt the user to sign up
phone_not_found	400	No account exists for this phone number (on login send/verify)	Fall back to a registration flow
email_already_registered	400	Email is already registered (on registration send)	Switch to the login flow
phone_already_registered	400	Phone number is already registered (on registration send)	Switch to the login flow
otp_invalid	400	Verification code is incorrect	Re-enter the code
otp_expired	400	No active code found, or it has expired	Request a new code
otp_max_attempts	400	Code locked after too many failed attempts	Request a new code
invalid_email	400	Email address is malformed	Correct the address
invalid_phone	400	Phone number is not valid E.164	Use E.164 format (e.g. +14155551234)
user_inactive	400	The end user is suspended or deleted. Returned both when an OTP is requested and when it is verified	Re-activate the end user in your application, or create a new one
email_not_configured	503	Email OTP requires a verified sending domain on the project	Verify a domain in Settings → Domains
sms_not_configured	503	Phone OTP requires configured SMS (Twilio) credentials. On the auth-OTP endpoints this is 503; the same code is returned as 400 by the direct SMS-send API (see Configuration Errors).	Configure Twilio in Settings → SMS
sms_send_failed	400	The SMS provider failed to send the code	Retry; if persistent, check the SMS provider configuration
otp_send_rate_limit_exceeded	429	Too many code requests for this identifier	Wait retry_after seconds before requesting another code
otp_verify_rate_limit_exceeded	429	Too many verification attempts for this identifier	Wait retry_after seconds before retrying

Password Errors

Code	HTTP Status	Description	Resolution
password_validation_error	400	Password doesn't meet the application's requirements	Check details; see the password-requirements endpoint
invalid_password	400	Password is incorrect (e.g. wrong current password on change-password)	Enter the correct password

Payment & Billing Errors

Code	HTTP Status	Description	Resolution
plan_upgrade_required	402 / 403	Feature or limit requires a plan upgrade. Status is route-dependent — mostly 403 (plan-gated features: webhooks, WaaS, organizations, Muse); 402 on a few paywall paths (e.g. custom domains). Branch on the code, not the status.	Upgrade your plan
subscriber_limit_exceeded	403	Subscriber cap for the current plan reached	Upgrade your plan
topic_limit_exceeded	403	Topic cap for the current plan reached	Upgrade your plan

Request Size

Code	HTTP Status	Description	Resolution
payload_too_large	413	Request body exceeds the maximum allowed size	See API Limits. The details object includes limit_bytes and received_bytes

Gaming Identity Errors

Native gaming identity endpoints (POST /v1/auth/game-center, POST /v1/auth/google-play-games) return intentionally opaque errors on any verification failure — the specific control that failed (signature, certificate chain, timestamp, bundle id, token exchange) is never disclosed, to avoid giving an attacker a probing oracle.

Code	HTTP Status	Description	Resolution
invalid_assertion	401	Apple Game Center assertion failed verification (any of: signature, certificate chain, timestamp freshness/replay, or bundle-id binding). Opaque by design.	Most common cause: sending the wrong player id. Send GKLocalPlayer.teamPlayerID (form T:_…) as playerId — this is the id GameKit signs over. gamePlayerID (A:_…) and the deprecated playerID fail even on an otherwise-perfect assertion. Also confirm a fresh assertion (within the ±5-min window) and a bundle id in the app's trusted allow-list.
invalid_auth_code	401	Google Play Games server auth code failed verification (invalid/expired code, token exchange failure, or player lookup failure). Opaque by design.	Send a fresh single-use serverAuthCode from requestServerSideAccess using the game's web/server client id.
provider_not_configured	401	The gaming provider isn't configured/enabled for this application.	Enable and configure the provider under Applications → [App] → OAuth → Native gaming identity.
environment_required	400	The request lacks the environment context needed to resolve provider config.	Ensure the application key resolves to a valid environment.

Resource Conflict Errors

Code	HTTP Status	Description	Resolution
slug_already_exists	409	A resource with this slug already exists in the project	Choose a different slug
reserved_slug	400	The slug is reserved and can't be used	Choose a different slug
workflow_key_exists	409	A workflow with this key already exists	Use a unique workflow key
topic_key_exists	409	A topic with this key already exists	Use a unique topic key
feature_not_available	403	The feature isn't available on your current plan	Upgrade your plan
email_unverified	403	The account's email isn't verified yet	Verify your account email before retrying

Operation Failures

Code	HTTP Status	Description	Resolution
send_failed	500	Message failed to send	Retry the request
provider_error	502	External provider (SES, Twilio, APNs) error	Retry; check provider status if persistent
rendering_error	400	Template rendering failed	Check template variables match the data provided
recipient_suppressed	400 / 422	Recipient is on the suppression list	Remove from the suppression list or skip

Workflow Errors

Code	HTTP Status	Description	Resolution
invalid_status_transition	400	The requested workflow status change isn't allowed from the current status	Check the current status; valid values are draft, active, paused, archived
workflow_not_active	400	The workflow can't be triggered because it isn't in the active status	Activate the workflow (PATCH /v1/workflows/{key}/status with {"status":"active"}) before triggering
step_keys_mismatch	400	The step_keys in a reorder request don't match the workflow's current steps	Send the exact set of existing step_keys in the desired order
execution_not_cancellable	400	The workflow execution is already in a terminal state and can't be cancelled	No action needed — the execution has finished

Internal Errors

Code	HTTP Status	Description	Resolution
internal_error	500	Unexpected server error	Retry; contact support if persistent
service_unavailable	503	Service temporarily unavailable	Retry with exponential backoff
timeout	504	Request timed out	Retry the request

Handling Errors

Retry Strategy

For transient errors (429, 500, 502, 503, 504), implement exponential backoff:

# Example: retry with backoff
for i in 1 2 4 8 16; do
  response=$(curl -s -w "\n%{http_code}" -X POST https://api.zyphr.dev/v1/emails \
    -H "X-API-Key: zy_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{"to": "user@example.com", "subject": "Hello", "html": "<p>Hi!</p>"}')

  status=$(echo "$response" | tail -1)
  if [ "$status" -lt 400 ]; then
    echo "Success"
    break
  fi
  echo "Retrying in ${i}s..."
  sleep $i
done

Idempotency

Use the Idempotency-Key header to safely retry requests without creating duplicates:

curl -X POST https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_live_your_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "html": "<p>Hi!</p>"}'