Errors
Every failed call returns the same JSON envelope with a stable code, so your code can react to the code and never to the wording.
These examples use a placeholder address. Your console shows the exact address of the API for your workspace.
The error format#
{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the scope messages.send.",
"request_id": "req_4f1c2b9a0d7e6f5a4b3c2d1e",
"details": {
"required_scope": "messages.send"
}
}
}codeis stable. Branch on it.messageis English and meant for developers. It can change.request_idis also in theX-Request-Idheader of every response. Quote it when you ask for help.detailsis an object ornull. A validation error lists the fields indetails.fields.
{
"error": {
"code": "invalid_request",
"message": "The request body is not valid.",
"request_id": "req_4f1c2b9a0d7e6f5a4b3c2d1e",
"details": {
"fields": [
{
"field": "to",
"issue": "must be E.164"
}
]
}
}
}What to retry#
429(rate_limited): wait the number of seconds inRetry-After, then retry.503(service_unavailable): retry with the sameIdempotency-Key. It is safe: the message is sent once.500(internal_error): retry once or twice with the sameIdempotency-Key, then contact us with the request id.- Other
4xxerrors mean the request itself must change. Retrying it unchanged fails again.
Error codes#
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request body, query or a header is not valid. The details list the fields. |
| 400 | idempotency_key_required | A message send needs an Idempotency-Key header. |
| 401 | authentication_required | The Authorization header is missing or malformed. |
| 401 | invalid_api_key | The API key is unknown. |
| 401 | api_key_revoked | The API key was revoked. |
| 401 | api_key_expired | The API key has expired. |
| 401 | application_inactive | The application is not active. |
| 401 | environment_mismatch | The key prefix does not match the environment of its application. |
| 403 | insufficient_scope | The API key does not have the scope this endpoint needs. |
| 403 | sandbox_only | This endpoint can only be called with a sandbox key. |
| 404 | not_found | The resource does not exist, or does not belong to your workspace. |
| 409 | idempotency_conflict | This Idempotency-Key was already used with a different request body. |
| 409 | connection_inactive | The connection is not active. |
| 422 | invalid_phone_number | The number cannot be turned into a WhatsApp number. |
| 422 | outside_customer_window | The customer has not written in the last 24 hours, so only a template can be sent. |
| 422 | template_not_found | No template with that name and language exists on this connection. |
| 422 | template_not_approved | The template exists, but it is not approved. |
| 422 | template_variables_mismatch | The number of variables does not match the template. |
| 429 | rate_limited | The key sent too many requests in the last minute. Wait for Retry-After seconds. |
| 429 | daily_send_limit_reached | The workspace reached its daily limit of live messages. |
| 500 | internal_error | Something went wrong on our side. Quote the request id to get help. |
| 503 | service_unavailable | WhatsApp or the database is unavailable. Retry with the same Idempotency-Key. |