What does an error look like?
404 Not Found
{
"error": {
"code": "not_found",
"message": "Session not found",
"request_id": "req_8f2c1a9d03b44e7a1c5d"
}
}Which error codes can I get?
| HTTP | code | Meaning |
|---|---|---|
| 400 | bad_request | The request could not be processed, for example the body is not valid JSON. |
| 401 | invalid_credentials | Missing, wrong or revoked API key. |
| 402 | payment_required | Your WhatsApp plan is not active. Renew it. |
| 402 | subscription_required | Sending or webhooks need a WhatsApp plan, and you have none. |
| 402 | subscription_expired | Your plan or trial ended. Sending and webhooks stop until you renew. |
| 403 | webhook_limit | You reached the number of webhooks your plan includes. |
| 409 | session_not_ready | The session is not connected, so it cannot send. |
| 422 | invalid_webhook_url | The webhook URL is not https on a public host. |
| 422 | invalid_phone | The phone number could not be read. |
| 422 | invalid_chat_id | The chat id is malformed. |
| 502 | gateway_unavailable | Temporary problem reaching WhatsApp. Retry with backoff. |
| 402 | session_limit | You reached the number of sessions your plan includes. |
| 403 | forbidden | The account is disabled. |
| 404 | not_found | Unknown session, chat, group, webhook, template or message. Also returned for sessions that belong to someone else. |
| 409 | conflict | The request conflicts with the current state of the resource. |
| 413 | payload_too_large | The request body is over 30 MB. |
| 422 | validation_error | A field is missing or invalid, including a webhook URL that is not public. |
| 429 | rate_limited | Too many requests. See Retry-After. |
| 501 | not_supported | The operation is not supported for this session. |
| 502 | upstream_error | WhatsApp could not complete the request. Safe to retry with backoff. |
How should I handle errors?
- 4xx (except 429): fix the request or the account state. Retrying will not help.
- 429: wait for
Retry-After, then retry. - 5xx: retry with exponential backoff.