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. Rate and usage limits can vary by account and operation; use the applicable endpoint and account terms instead of a universal call-rate table.
Recover a send safely
- Save the requested target, channel, correlation values and any returned message/broadcast IDs.
- Check the business result and each recipient's
errors. Compare requested and returned recipients; omitted rows do not establish success. - Confirm message outcomes with the currently supported webhook events, message history or status capability for that channel. Keep accepted, sent, delivered, read and failed distinct.
- For an unknown result, reconcile the original attempt before retrying. Do not resend the whole batch to recover a subset.
broadcast_nameandlocal_message_idare not a general request-level idempotency guarantee.
See the V3 template recipe for code that checks business and recipient results without automatic resends.