Common Meta API errors

When a send fails, Callduck normalizes Meta's Cloud API error into a short, safe, human-readable reason and appends (code <n>) when Meta returns a numeric code. The failed message is stored with status: FAILED and the reason on its error / errorReason. Webhook verification and signature problems are recorded in the audit log. The decision to fail is Meta's; Callduck reflects and explains it.

How Callduck surfaces an error

• Send errors → the message is marked FAILED with the normalized reason (e.g. "Invalid OAuth access token (code 190)"); the channel health check turns unhealthy when credentials are bad.
• Template status → rejected templates mirror Meta's status and rejection reason via template sync and message_template_status_update.
• Webhook problems → written to the audit log (webhook.verification_failed, webhook.signature_invalid).

Frequent errors and fixes

• Invalid / expired access token — code 190. Surfaced: send FAILED with "(code 190)"; health check unhealthy. Fix: generate a fresh permanent System User token, update the channel or WHATSAPP_ACCESS_TOKEN, and retry.
• Unregistered phone number. Surfaced: send FAILED with Meta's normalized message. Fix: register the production number in Meta → WhatsApp → API Setup (verify by SMS/voice) before sending.
• Template not found / not approved — codes ~132xxx (e.g. 132000 / 132001 / 132007). Surfaced: send FAILED with the normalized reason; the template's mirrored status shows Pending or Rejected with Meta's reason. Fix: wait for approval, fix the rejection and resubmit, or send only APPROVED templates with matching language and variables.
• Re-engagement / outside the 24-hour window — code 131047. Surfaced: a session text outside the window returns FAILED; marketing/broadcast sends exclude non-opted-in contacts and warn first. Fix: use an approved template to (re)open the conversation; only message recipients who opted in.
• Recipient not in allowed list (development/test numbers). Surfaced: send FAILED with Meta's normalized message. Fix: add the number to the app's allowed recipient list, or move the app/number out of development mode.
• Rate limit — code 80007 (and related throughput limits). Surfaced: send FAILED with the normalized error. Fix: slow the send rate and spread volume; messaging tiers are raised by Meta as you send quality traffic to verified numbers.
• Webhook signature mismatch. Surfaced: webhook POST returns 401 in production (acknowledged-but-skipped in non-prod) with a webhook.signature_invalid audit entry. Fix: ensure the channel app secret matches the Meta app's secret exactly (see App secret & webhook signatures).
• Verify-token mismatch (handshake). Surfaced: GET returns 403 with a webhook.verification_failed audit entry; Meta shows the webhook unverified. Fix: set the identical verify token in Callduck, Meta's webhook config, and WHATSAPP_VERIFY_TOKEN.

> Codes can change and Meta may return errors not listed here; Callduck always passes through Meta's own message text so you can act on the exact reason. For deeper detail, consult Meta's official Cloud API error reference.

See Meta Cloud API, Message template approval, and App secret & webhook signatures.