Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Handle API errors and request rate limits

Most send failures return success: false, error, and error_code. Other endpoints can return their own validation structure, including an errors array. Handle the endpoint's documented response instead of assuming every error body is identical.
{
  "success": false,
  "error": "Insufficient wallet balance to send this message.",
  "error_code": "insufficient_balance"
}

Authentication and ownership

  • 401 unauthorized: missing, invalid, expired, or revoked Bearer key.
  • 403 forbidden: the key lacks the required scope.
  • 404: contact, list, template, or automation unavailable in the current workspace.
Fix credentials or ownership before retrying. Repeated authentication errors will not recover through backoff alone.

Request and idempotency errors

  • 400 idempotency_key_required: missing/oversized message request key.
  • 409 idempotency_conflict: a key was reused for different request data.
  • 409 idempotency_in_progress: an identical-key request is still processing.
  • 422: invalid channel/phone/email, missing message/subject, missing variables, archived template, or invalid contact data.
Correct validation failures as new logical requests, with new keys when payloads change. Preserve the existing key after uncertainty or in-progress responses.

Channel readiness and recipients

Send validation can report whatsapp_not_connected, recipient_not_on_whatsapp, sender_id_required, email_sender_required, email_sender_not_found, or email_suppressed. Check the actual channel state and recipient preferences before creating another send.

Funds and rate limits

402 includes insufficient wallet balance or monthly plan limit. 429 includes API throttling, OTP controls (otp_*), and marketing email frequency limits. A retry is useful only after the relevant allowance, waiting period, or restriction changes.
Current application throttle defaults: 300 API requests per minute per IP; 60 message-create requests per minute per key; 120 event/identify/automation-intake requests per minute per key. Separate provider, OTP, sender, SMTP, plan, and daily capacity limits also apply.
Honor Retry-After where supplied and use backoff rather than a tight loop. A batch request queues paced delivery; it is not a means to evade provider limits.

Provider errors and ambiguous outcomes

502 send_failed, sms_failed, or email_failed indicate a provider-related failure. Inspect the existing send record and provider ID. A network timeout can occur after acceptance, so blindly creating another request with a new key can duplicate delivery.
Next: follow troubleshooting and safe retries.
No universal retry rule fits every endpoint. Verify the failure code and whether the provider may already have accepted the work.