Errors

The source meta or whabuzz contract, the WhaBuzz error codes, and how to read Meta's errors.

Every error response says who produced it, in the body and in a header. Check source first.

The header X-WhaBuzz-Error-Source: whabuzz or meta repeats it, so you can branch without parsing JSON.

#WhaBuzz errors

{
  "source": "whabuzz",
  "error": {
    "code": "number_not_connected",
    "message": "Number 1013622581841046 is not connected.",
    "details": { "connection_detail": "no_verified_endpoint" }
  },
  "request_id": "req_01JAB3W1Z4B7D0F3H6K9N2Q5S8"
}

Always log request_id (also the X-WhaBuzz-Request-Id header). It is what support looks up.

meta_unreachable is the one to handle carefully: the message may or may not have been sent. Retry with the same Idempotency-Key (see Idempotency) rather than composing a new send.

#Reading Meta errors

When Meta refuses a call, you get Meta's HTTP status and Meta's error object under error, unchanged:

{
  "source": "meta",
  "error": {
    "message": "(#131030) Recipient phone number not in allowed list",
    "type": "OAuthException",
    "code": 131030,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Recipient phone number not in allowed list: Add recipient phone number to recipient list and try again."
    },
    "error_subcode": 2655007,
    "fbtrace_id": "AqN2fZtPLm1oV0xK3wRhjQe"
  }
}

Reading it:

• error.code is the number to branch on. WhaBuzz never rewrites it.
• error.error_data.details is Meta's plain-language explanation. Show it in your logs.
• error.fbtrace_id is what Meta support asks for. Keep it.
• The HTTP status is Meta's: 4xx means your request or account state, 5xx means Meta's side. Do not auto-retry 4xx.

The example above, 131030, is what you get while a WABA is in test mode and the recipient is not on its allowed list. Add the number to the list in Meta's manager, or finish business verification.

Common ones: 131047 (re-engagement: the 24-hour window is closed, use a template), 131026 (message undeliverable), 132000 series (template parameter problems), 130429 (throughput), 131056 (pair rate limit), 190 (token expired or invalid; reconnect the number).

If Meta's response is not JSON, WhaBuzz wraps it as {"source":"meta","error":{"raw_body":"<first 4 KB>"}}.

The complete list, with Meta's recommended fix for each, is in Meta's documentation: Cloud API error codes.

#Errors inside events

Failures after acceptance arrive as events, not HTTP errors: a message.status with status: "failed" carries status.errors[] in Meta's format. The same error.code numbers apply.

This page as Markdown: /errors.md. All docs in one file: /llms-full.txt.