Rate limits and errors
Errors have one shape and stable codes, so your code can branch on the code and show people the message.
Error shape#
Every error answers JSON { "error": "<code>", "message": "<one English sentence>" }. Branch on error; the message may change. A hidden chat, an id from another workspace and a malformed id all answer 404 not_found, the same way.
Rate limits#
- Each key may make 600 requests per minute.
- Failed key lookups are limited per address.
- Replay: 10 per minute per webhook endpoint.
- Connect sessions: 30 per minute per key and 200 per day per workspace.
Over a limit, Wagent answers 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry with the same Idempotency-Key.
Error codes#
| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | The API key is missing, unknown, revoked or not valid for this workspace. |
ip_not_allowed | 403 | This address is not on the agent's allowed addresses. |
read_only_key | 403 | This key is read only, so it cannot change anything. |
agents_paused | 403 | Agents are paused by the workspace owner. |
agent_off | 423 | This agent is switched off by the workspace owner. |
approvals_off | 403 | Approving through the API is off for this agent. |
own_item | 403 | A key cannot approve its own agent's items. |
tool_off | 403 | The workspace owner has not turned this tool on for this agent. |
trial_limit | 403 | This number reached its trial limit. |
blocked | 403 | The owner's rules do not allow this. |
not_found | 404 | Not found. |
invalid | 400 | The request is not valid. |
idempotency_key_required | 400 | Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write. |
idempotency_key_mismatch | 422 | This Idempotency-Key was already used with a different request. |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still running. Retry shortly. |
already_requested | 409 | This request was already made. |
widget_unavailable | 409 | This workspace cannot connect numbers through the widget until it has an active plan. |
session_expired | 410 | This connect session is used, expired or not valid. Ask the app for a new one. |
origin_not_allowed | 403 | This site is not on the publishable key's allowed sites. |
not_pending | 409 | This item is no longer waiting. |
event_sending | 409 | This event is being delivered right now. Retry in a few seconds. |
rate_limited | 429 | Too many requests. Retry after the time in Retry-After. |
send_failed | 502 | WhatsApp did not accept the message. Nothing was delivered. |
unavailable | 503 | Wagent could not complete this request, so nothing was done. Try again shortly. |
Each operation in the API reference lists the codes it can answer.