Skip to content

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#

403 Forbidden
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key lacks the scope messages.send.",
    "request_id": "req_4f1c2b9a0d7e6f5a4b3c2d1e",
    "details": {
      "required_scope": "messages.send"
    }
  }
}
  • code is stable. Branch on it.
  • message is English and meant for developers. It can change.
  • request_id is also in the X-Request-Id header of every response. Quote it when you ask for help.
  • details is an object or null. A validation error lists the fields in details.fields.
400 Bad Request
{
  "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 in Retry-After, then retry.
  • 503 (service_unavailable): retry with the same Idempotency-Key. It is safe: the message is sent once.
  • 500 (internal_error): retry once or twice with the same Idempotency-Key, then contact us with the request id.
  • Other 4xx errors mean the request itself must change. Retrying it unchanged fails again.

Error codes#

Every error code of the public API
HTTPCodeMeaning
400invalid_requestThe request body, query or a header is not valid. The details list the fields.
400idempotency_key_requiredA message send needs an Idempotency-Key header.
401authentication_requiredThe Authorization header is missing or malformed.
401invalid_api_keyThe API key is unknown.
401api_key_revokedThe API key was revoked.
401api_key_expiredThe API key has expired.
401application_inactiveThe application is not active.
401environment_mismatchThe key prefix does not match the environment of its application.
403insufficient_scopeThe API key does not have the scope this endpoint needs.
403sandbox_onlyThis endpoint can only be called with a sandbox key.
404not_foundThe resource does not exist, or does not belong to your workspace.
409idempotency_conflictThis Idempotency-Key was already used with a different request body.
409connection_inactiveThe connection is not active.
422invalid_phone_numberThe number cannot be turned into a WhatsApp number.
422outside_customer_windowThe customer has not written in the last 24 hours, so only a template can be sent.
422template_not_foundNo template with that name and language exists on this connection.
422template_not_approvedThe template exists, but it is not approved.
422template_variables_mismatchThe number of variables does not match the template.
429rate_limitedThe key sent too many requests in the last minute. Wait for Retry-After seconds.
429daily_send_limit_reachedThe workspace reached its daily limit of live messages.
500internal_errorSomething went wrong on our side. Quote the request id to get help.
503service_unavailableWhatsApp or the database is unavailable. Retry with the same Idempotency-Key.