Errors
The error format, every error code, and which errors to retry.
The API uses HTTP status codes: 2xx succeeded, 4xx is a problem with the request, 5xx is a problem on our side or WhatsApp's.
Error format
Every error body has a detail field. For send and template errors, detail is an object with a stable code. Branch on code, not on message, which is for humans and may change.
{
"detail": {
"code": "provider_rate_limited",
"message": "provider rate limit",
"retry_after_ms": 2000
}
}| Field | Description |
|---|---|
code | Machine-readable error code, from the tables below. |
message | Human-readable explanation. |
retry_after_ms | Only for provider_rate_limited: how long to wait before retrying. |
For auth errors detail is a string ("missing bearer token"). For an invalid request body (422) it is a list with one entry per invalid field:
{
"detail": [
{ "loc": ["body", "recipient"], "msg": "Field required", "type": "missing" }
]
}Codes
Authentication and access
| HTTP | Meaning | What to do |
|---|---|---|
| 401 | Token missing, expired or invalid. | Get a new token and retry once. |
| 403 | The token may not act on this number or tenant. | Check owned_numbers in GET /v1/me. |
Sending and templates
| HTTP | code | Meaning | Retry? |
|---|---|---|---|
| 404 | auth_unknown_sender | The number in the path is not connected. | No |
| 422 | validation_error | The request is invalid. | No, fix it |
| 422 | provider_permanent | WhatsApp rejected the message or template. | No |
| 429 | provider_rate_limited | Too many requests for this number. | Yes, after retry_after_ms |
| 503 | provider_retryable | Temporary failure. | Yes, with backoff |
Configured messages
| HTTP | Meaning | Retry? |
|---|---|---|
| 422 | Invalid receiver, message or params. | No, fix it |
| 502 | No configured message with that name, or it could not be built. | No |
| 503 | Temporarily unavailable. | Yes, with backoff |
Other
| HTTP | Meaning |
|---|---|
| 404 | The resource does not exist: an unknown message_uuid, or no webhook configuration yet. |
Batch errors
send/batch answers 200 even when some messages fail. Each failed item carries the same code and message in its own error field. Retry only the failed items whose code is retryable.