Errors

The API uses standard HTTP status codes. 2xx means success, 4xx means something in the request needs fixing, and 5xx means a temporary problem on our side or WhatsApp's.

WhatsApp errors use Meta's format:

{
  "error": {
    "message": "(#131009) Parameter value is not valid",
    "type": "OAuthException",
    "code": 131009,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Please check the phone number."
    },
    "fbtrace_id": "AbCdEfGh123"
  }
}

Log error.message and error_data.details for yourself; they aren't written for customers. Include fbtrace_id when you contact support.

A 200 response means WhatsApp accepted a message, not that it was delivered. Some problems are found only later. They arrive as a failed message status with the same error codes.

Common error codes

• 100: a parameter is missing or invalid. Compare your request with this reference.
• 130429: you're sending faster than your number's throughput allows. Slow down and retry with backoff.
• 131000: the message failed for an unknown reason. Retry once, then contact support.
• 131009: a parameter value is invalid, often the phone number. Check error_data.details.
• 131016: a WhatsApp service is temporarily unavailable. Retry with backoff.
• 131021: the sender and recipient are the same number.
• 131026: the message couldn't be delivered. The number may not use WhatsApp, or the customer runs an old app version.
• 131047: more than 24 hours since the customer last messaged you. Send a template instead.
• 131051: unsupported message type. Check the type field.
• 131056: too many messages to the same customer in a short time. Wait before messaging them again.
• 132000: the number of template parameters doesn't match the template.
• 132001: the template doesn't exist in this language, or isn't approved yet.
• 132015: template parameters are invalid or missing.
• 133004: the WhatsApp server is temporarily unavailable. Retry with backoff.
• 133010: your number isn't registered on the WhatsApp Business Platform. Contact support.
• 368: your account is temporarily blocked for a policy violation. Contact support.

Errors from HostMentor use a simpler format, { "error": "code", "message": "…" }:

• 400 phone_number_id_required: your team has more than one WhatsApp number and this request doesn't say which. Add ?phone_number_id=….
• 401 invalid_api_key: the apikey header is missing, wrong or revoked.
• 403 account_suspended: your team's WhatsApp API plan isn't active (renew it on the dashboard), or the number is suspended (contact HostMentor). Sending resumes within a minute of either being fixed.
• 403 endpoint_not_allowed: the endpoint isn't part of the HostMentor WhatsApp API. Use the endpoints in this reference.
• 403 webhook_managed_by_hostmentor: webhooks are set on the dashboard, not through the API.
• 404 number_not_found: the phone_number_id, waba_id or wanumber in the request isn't one of your team's numbers.
• 429 rate_limited: more than 1,000 requests in 10 seconds with one key. Slow down and retry.
• 502 upstream_unreachable: WhatsApp couldn't be reached. Retry with backoff.
• 503 gateway_unavailable: HostMentor couldn't check your key just then. Retry in a few seconds.