--- updatedAt: 2026-11-03T06:20:12.000Z agentTools: projectIndex: https://docs.wati.io/llms.txt --- # Errors & Rate Limits Understand WATI HTTP error responses and rate limits when handling API requests. Inspect HTTP status, the endpoint's business result, and the final message outcome separately. A successful HTTP response can contain a business failure; accepted messages are not necessarily delivered. ## HTTP and business outcomes | Outcome | How to handle it | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2xx | Parse the documented response. V3 template send/schedule can return `success:false` with `error` in HTTP 200. Even `success:true` can include recipient errors or omit invalid recipients. | | 400 | Correct the documented validation/business error before retrying. V3 errors commonly use `code`, `message`, `timestamp`; use the operation's schema. | | 401 | Check authentication and endpoint eligibility. For example, the current V3 contact-update handler rejects the TRIAL role and can return plain text. A 401 does not universally have a JSON body. | | 403 | Check scopes, roles, workspace, channel, plan and other account restrictions. More token scopes do not override every restriction. | | 404 / 405 | Check the resource, documentation version, route and HTTP method. | | 429 | Check whether the refusal is a request rate, account usage or plan limit. Honor `Retry-After` when supplied; do not assume the header is always present. Use bounded backoff for retryable rate limits; resolve quota/plan restrictions first. | | 5xx / timeout / connection loss | A write may already have been accepted. Treat its result as unknown and reconcile before resending. | Authentication/authorization failures can be plain text or empty. Do not force every error into one JSON envelope. Legacy endpoints can use their own `ok`, `result` or `info` business fields; consult that endpoint instead of applying the V3 shape. ## V3 request batch limits | Operation | Request boundary | Additional checks | | -------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | PUT `/api/ext/v3/contacts` | 1–100 contacts | The current handler denies the TRIAL role; other endpoint permissions still apply. | | POST `/api/ext/v3/messageTemplates/send` | 1–10,000 recipients | Balance, broadcast-size, usage, channel and account restrictions can reduce what is accepted. | | POST `/api/ext/v3/messageTemplates/schedule` | 1–10,000 recipients | Same account checks; a current/past scheduled time can be processed immediately. Generate a future UTC value when scheduling. | Batch size is not a per-second rate limit or an entitlement to send that volume. Legacy V1/V2 limits do not establish V3 limits. The published legacy request-rate baselines below are separate from these V3 batch limits; account and operation policies still apply. ## Published plan request-rate baselines The [developer website](https://www.wati.io/developer/) publishes these baselines for the listed **legacy V1 operations**. Values are requests per 10 seconds; a bulk request and the recipients inside it are different units. | Legacy operation | Growth | Pro | Business | | ----------------------------- | --------- | --------- | ---------- | | `/addContact`, `/getContacts` | 10 / 10 s | 10 / 10 s | 10 / 10 s | | `/getMessages` | 10 / 10 s | 10 / 10 s | 10 / 10 s | | `/sendTemplateMessage` | 30 / 10 s | 60 / 10 s | 100 / 10 s | | `/sendTemplateMessages` | 30 / 10 s | 60 / 10 s | 100 / 10 s | Use the operation's full tenant-prefixed route, including its required path/query parameters. These are the published plan baselines, not measurements of a particular account's effective policy. Custom account or route policies can differ. **Do not apply this table as a fixed limit for all V3 endpoints**: V3 rate/usage policies are account- and resource-specific. For a higher or confirmed account limit, check your account agreement or contact WATI support. A 429 can come from a request-rate limit, usage quota or a feature-specific limit. Honor `Retry-After` when it is present; no single header or error envelope is promised for every refusal. Use bounded backoff for a retryable rate limit, and resolve exhausted quotas or eligibility before retrying. Send requests with unknown outcomes still require reconciliation. ## Recover a send safely 1. Save the requested target, channel, correlation values and any returned message/broadcast IDs. 2. Check the business result and each recipient's `errors`. Compare requested and returned recipients; omitted rows do not establish success. 3. Confirm message outcomes with the currently supported [webhook events](https://docs.wati.io/v2.6/reference/introduction-1), message history or status capability for that channel. Keep accepted, sent, delivered, read and failed distinct. 4. For an unknown result, reconcile the original attempt before retrying. Do not resend the whole batch to recover a subset. `broadcast_name` and `local_message_id` are not a general request-level idempotency guarantee. See [the V3 template recipe](https://docs.wati.io/v2.6/recipes/send-template-messages-v3) for code that checks business and recipient results without automatic resends. For credential expiry, role-specific scopes and safe token replacement, follow [Authentication and token lifecycle](https://docs.wati.io/reference/authentication#diagnose-before-replacing-credentials). Do not regenerate credentials automatically for every 401/403 or retry an uncertain send without reconciliation.