msgbubblesDocs

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

StatusCodeMeaning
429monthly_quota_exceededYour 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.
409pooled_recipient_conflictThe 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.
400invalid_requestThe request body, query, or path failed validation — a missing, unknown, or malformed field.
400invalid_handleto / from_handle is not a valid E.164 number or iMessage email.
400invalid_from_handleThe from number is not assigned to your account (or has no connected WhatsApp session when channel is forced).
400invalid_attachmentsAn attachment_id is unknown or already used by another message.
400invalid_urlA webhook url isn’t a public http(s) endpoint (private, loopback, or link-local addresses are rejected).
401unauthorizedMissing or invalid API key.
403forbiddenValid key, inactive account.
404not_foundThe resource doesn’t exist — or belongs to a different account.
409conflict, not_a_group, chat_conflictThe 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.
409recipient_opted_outThe recipient replied STOPon one of your shared numbers. Nothing was sent. Don’t retry until they reply START. See Opt-outs.
400 / 409unsupportedThe 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.
413file_too_largeA multipart upload exceeds 25 MB per file, or a presign’s declared size_bytesexceeds 100 MB.
429rate_limitedRate limit exceeded; retry after the window resets.
503participant_add_disabled, participant_remove_disabledAdding 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, unavailableA 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-Remaining and X-RateLimit-Reset (seconds until the window resets). Exceeding the limit returns 429 with a Retry-After header in seconds.
  • Outbound message throughput is additionally paced per sending number to protect deliverability — bursts queue rather than fail, so a 202 means 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-Key so network-level retries can’t double-send.
  • 5xx responses and 429 are 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.