Errors & limits
Every error has the same shape:
{ "error": "invalid_from_handle", "message": "from_handle is not a number assigned to your account", "request_id": "req_…" }error is a stable machine-readable code (branch on this, not the HTTP status or the human message); message is human-readable and may change. request_id is on every response — success or error — and is mirrored by the X-Request-Id header; quote it when reporting a problem. A 5xx never includes internal detail.
Common codes
| Status | Code | Meaning |
|---|---|---|
| 429 | monthly_quota_exceeded | Your organization’s monthly message allowance is exhausted. No new send is queued. Wait for the UTC calendar-month reset using Retry-After, or contact your administrator to raise the limit. Check usage. |
| 409 | pooled_recipient_conflict | The recipient is reserved by another organization on this pooled number. No message was queued. Select another granted number; retrying the same pair will not resolve the conflict. |
| 400 | invalid_request | The request body, query, or path failed validation — a missing, unknown, or malformed field. |
| 400 | invalid_handle | to / from_handle is not a valid E.164 number or iMessage email. |
| 400 | invalid_from_handle | The from number is not assigned to your account (or has no connected WhatsApp session when channel is forced). |
| 400 | invalid_attachments | An attachment_id is unknown or already used by another message. |
| 400 | invalid_url | A webhook url isn’t a public http(s) endpoint (private, loopback, or link-local addresses are rejected). |
| 401 | unauthorized | Missing or invalid API key. |
| 403 | forbidden | Valid key, inactive account. |
| 404 | not_found | The resource doesn’t exist — or belongs to a different account. |
| 409 | conflict, not_a_group, chat_conflict | The action doesn’t apply: editing an SMS, reacting before delivery, group ops on a DM or WhatsApp group, retrying a non-failed message. chat_conflict means a group create was delivered into an existing group not linked to your account — the message went out, so don’t retry. |
| 409 | recipient_opted_out | The recipient replied STOPon one of your shared numbers. Nothing was sent. Don’t retry until they reply START. See Opt-outs. |
| 400 / 409 | unsupported | The sending number’s channel can’t do this — e.g. sending into a group (400) or a typing indicator (409) from a number that doesn’t support it. |
| 413 | file_too_large | A multipart upload exceeds 25 MB per file, or a presign’s declared size_bytesexceeds 100 MB. |
| 429 | rate_limited | Rate limit exceeded; retry after the window resets. |
| 503 | participant_add_disabled, participant_remove_disabled | Adding or removing group members is temporarily unavailable. Nothing was changed, and retrying returns the same error until it’s available again. See Manage a group. |
| 502 / 503 | *_failed, device_offline, unavailable | A synchronous upstream action failed or the sending number is temporarily offline. Safe to retry. |
Rate limits
- API requests are limited per key (default 120 requests/minute). If you need more, ask us to raise your account’s limit.
- Every response carries
X-RateLimit-Limit(your key’s limit),X-RateLimit-RemainingandX-RateLimit-Reset(seconds until the window resets). Exceeding the limit returns429with aRetry-Afterheader in seconds. - Outbound message throughput is additionally paced per sending number to protect deliverability — bursts queue rather than fail, so a
202means the message will go out as capacity allows.
Monthly allowances are shared across all of an organization’s keys and numbers. Read your current allowance with GET /v1/usage. An exhausted allowance returns 429 monthly_quota_exceeded; the existing per-key request limiter returns 429 rate_limited.
Retries
- Always send with an
Idempotency-Keyso network-level retries can’t double-send. 5xxresponses and429are safe to retry with backoff.4xx(other than 429) are not — fix the request. For group creation, an error or timeout may follow a delivered opening message and still consumes a monthly slot; check the conversation before attempting another send.- Once a send is accepted (
202), retries are our job, not yours: queued messages retry automatically per the send retry policy, and webhook deliveries retry with their own backoff.