Skip to Content
Developers

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
  }
}
FieldDescription
codeMachine-readable error code, from the tables below.
messageHuman-readable explanation.
retry_after_msOnly 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

HTTPMeaningWhat to do
401Token missing, expired or invalid.Get a new token and retry once.
403The token may not act on this number or tenant.Check owned_numbers in GET /v1/me.

Sending and templates

HTTPcodeMeaningRetry?
404auth_unknown_senderThe number in the path is not connected.No
422validation_errorThe request is invalid.No, fix it
422provider_permanentWhatsApp rejected the message or template.No
429provider_rate_limitedToo many requests for this number.Yes, after retry_after_ms
503provider_retryableTemporary failure.Yes, with backoff

Configured messages

HTTPMeaningRetry?
422Invalid receiver, message or params.No, fix it
502No configured message with that name, or it could not be built.No
503Temporarily unavailable.Yes, with backoff

Other

HTTPMeaning
404The 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.

On this page