WhatsApp & Meta API Error Code Lookup

What it means: Meta is rejecting the send because the page access token does not have the pages_messaging permission, or that permission was revoked (commonly after a Page admin removes app access, or the app review/permission grant expires).

What to do: Reconnect the Page in Meta Business Suite, re-grant pages_messaging during the OAuth flow, and re-authorize the integration. Retrying the same request will not fix this -- the token itself is missing the scope.

What it means: The recipient is unreachable on Messenger/Instagram for this send -- usually because they've blocked the page, deactivated their account, or Meta is rate-limiting sends to that specific user for spam-prevention reasons.

What to do: Don't retry. Mark the conversation as undeliverable and stop further automated sends to that contact -- retrying just burns your sending reputation without succeeding.

What it means: The long-lived Page or User access token used to call the Graph API has expired, was revoked, or never matched the requested permission scope ("Error validating access token: Session has expired…").

What to do: Re-run the OAuth connection flow for that channel. Long-lived Page tokens typically last ~60 days and need silent refresh before expiry -- if you see this in bulk, your token-refresh cron likely stopped running.

What it means: Two different real causes share this code: (1) the PSID (person-scoped ID) you're trying to message isn't addressable from this Page token -- a permanent, per-user limitation, not a bug; (2) calling the Profile API (GET /{psid}) instead of the Conversations API to resolve a sender's name, which several Page tokens simply don't have the capability for.

What to do: For messaging: there's no fix for that specific PSID/token pair -- it's a Meta-side addressability limit, log it at debug level and move on. For name resolution: switch from GET /{psid} to GET /{page_id}/conversations?fields=participants and read the name from the participants list instead.

What it means: Your app's current permission grant for this Page doesn't include the capability the endpoint requires -- frequently seen on the Profile API after a Page reconnects via the Instagram Direct flow instead of the Facebook Page flow.

What to do: Reconnect the integration using the correct OAuth flow for the platform (Page-based, not Instagram-direct) so the app is granted the full capability set, then retry.

What it means: You tried to hide/moderate a comment that's already hidden -- typically because two ingestion paths (a webhook delivery and a retry cron) raced on the same comment and both tried to act on it.

What to do: Treat this as an idempotent success, not an error: the desired end state (hidden) is already achieved. Log it and move on -- no remediation needed.

What it means: You've exceeded Meta's call volume limit for this app or endpoint in the current window.

What to do: Back off and retry with exponential delay. If this is frequent, check whether you're polling instead of using webhooks, or whether multiple processes are hitting the same endpoint redundantly.

What it means: More than 24 hours have passed since the customer last messaged you, so WhatsApp will no longer deliver a free-form message. Outside that customer-service window, only pre-approved template messages are deliverable.

What to do: Don't retry the same payload -- it will fail every time. Send an approved template message instead, or wait until the customer messages you again to reopen the 24-hour window.

What it means: WhatsApp accepted the request but can't deliver to this recipient. Common real causes: the number isn't on WhatsApp, the user is on a very old WhatsApp version, or the recipient hasn't accepted Meta's newer Terms of Service.

What to do: Verify the number actually has WhatsApp before further sends. If it does, this is a recipient-side state you can't fix from the API -- suppress automated retries so you don't burn quality rating on undeliverable traffic.

What it means: Meta blocked this marketing template delivery to "maintain healthy ecosystem engagement" -- the recipient has recently received too many marketing messages (from you or from businesses overall), so WhatsApp is per-user throttling promotional volume.

What to do: Don't immediately retry -- the cap is on the recipient, not your request. Space out marketing sends per contact, prioritize utility conversations, and re-attempt the campaign send after a cool-down (typically 24h+).

What it means: There's a billing problem on the WhatsApp Business Account: missing or failed payment method, expired credit line, or the account hit its spend limit. All paid conversation categories start failing at once when this fires.

What to do: Fix the payment method / billing setup in WhatsApp Manager (Business Settings → Billing). Sends will keep failing until billing is healthy -- queue outbound messages instead of retrying into a wall.

What it means: Your WhatsApp Business Account exceeded its allowed request throughput (pair, business-use-case, or API call volume limits on the Cloud API).

What to do: Retry with exponential backoff and add client-side throttling per phone-number pair. If you hit this at normal volume, check for duplicate senders or retry storms in your own pipeline.

What it means: Too many messages sent to the same recipient phone number in a short window. Meta rate-limits each business-to-consumer number pair to prevent spam bursts.

What to do: Queue and space messages to the same contact (a few seconds apart is usually enough). Batch consecutive lines into one message instead of sending each line separately.

What it means: The business phone number you're sending from isn't registered with the Cloud API -- typical right after migrating from On-Premises API, after a certificate change, or when the registration was never completed.

What to do: Complete the /register call for the phone number (or re-register after migration) in WhatsApp Manager or via the API, then retry. Until registration completes, every send from that number fails.

What it means: The template name doesn't exist for this WhatsApp Business Account, or it exists but not in the language code you passed. A template pending review or rejected also resolves to this.

What to do: Check the exact template name and language code against WhatsApp Manager (they must match exactly, including locale suffixes like en_US vs en). If the template is still in review, wait for approval before sending.

What it means: Meta has temporarily restricted the account or app from the action because automated systems or reviewers flagged policy violations (spam reports, quality drops, or messaging-policy breaches).

What to do: Stop automated sends immediately -- retrying during a block deepens it. Check Account Quality in Meta Business Suite for the violation and appeal or wait out the restriction, then ramp volume back up slowly.