WhatsApp & Meta API Error Code Lookup

What it means: Meta accepted the request but could not deliver the message to this recipient. Meta lists causes such as: the number is not on WhatsApp, the recipient has not accepted WhatsApp's newer Terms of Service and Privacy Policy, or the recipient is on an outdated WhatsApp version. The error often arrives later on the message status webhook instead of in the send response, and it does not tell you which cause applies.

What to do: Confirm the number is on WhatsApp before you send again, and do not retry the same send in a loop. Instant Reply stops sending to a number after a 131026 so a dead number does not keep using quota or hurting your quality rating. If you run your own sender, suppress the number the same way.

What it means: More than 24 hours have passed since the customer last messaged you, so WhatsApp will not deliver a free-form message. Outside that customer service window, only approved template messages can be sent.

What to do: Do not retry the same payload. It fails every time. Send an approved template message instead, or wait until the customer messages you again, which reopens the 24-hour window.

What it means: Meta did not deliver this marketing template "to maintain healthy ecosystem engagement". The limit is applied per recipient, so this person has recently received a lot of marketing messages. Meta decides this after it accepts your request, so you cannot predict it before sending. Instant Reply's region check also treats marketing templates to US numbers as failing with this code since Meta's April 1, 2025 pause; confirm the current rule in Meta's documentation.

What to do: Do not retry immediately: the limit is on the recipient, not on your request. Space out marketing sends per contact, favor utility and service conversations, and try the campaign again later. If a template keeps hitting this code, review its category and content.

What it means: The recipient chose to stop receiving marketing messages from your business, so Meta rejects marketing templates to that number.

What to do: Stop sending marketing templates to this contact and record it as an opt-out in your own system. Retrying cannot succeed.

What it means: Too many messages went from your business number to the same recipient in a short window. Meta rate-limits each business-to-consumer pair.

What to do: Queue messages to the same contact and back off before retrying. Meta documents a backoff of 4^X seconds, starting at X=0 and increasing after each failure. Combine consecutive lines into one message instead of sending each line separately.

What it means: Meta restricted how many messages your business number can send because too many earlier messages were blocked or flagged as spam by recipients.

What to do: Pause sending and let the restriction clear before retrying. Then look at why recipients flag you: check opt-in quality, message frequency, and your quality rating in WhatsApp Manager.

What it means: Your sending throughput from this business number exceeded the Cloud API limit. This is Meta's error code, separate from an HTTP 429 status.

What to do: Retry with exponential backoff and throttle on your side. If you see it at normal volume, look for duplicate senders or a retry storm in your own pipeline.

What it means: Your WhatsApp Business Account exceeded the request rate Meta allows for it.

What to do: Retry with exponential backoff and add client-side throttling. If it happens at normal volume, check for duplicate senders or retry storms in your own pipeline.

What it means: A generic error on Meta's side. It does not describe a specific problem with your request.

What to do: Retry with backoff. If it keeps happening for the same payload, check the request against the Cloud API reference and contact Meta support with the response's fbtrace_id.

What it means: Meta could not upload or process the media file in your message. It is often a temporary failure, but an unsupported file type or size can cause it too.

What to do: Retry once or twice with backoff. If it still fails, check the file type and size against Meta's media limits and re-upload the file.

What it means: The message type in your request is not supported for this send.

What to do: Change the message type or payload. Retrying the same request returns the same error.

What it means: There is a billing problem on the WhatsApp Business Account, such as a missing, failed, or expired payment method or a credit line problem. Messages that need billing fail until it is fixed.

What to do: Fix the payment method in your Meta Business account's WhatsApp payment settings. Queue outbound messages until billing is healthy instead of retrying into the error.

What it means: Meta locked your WhatsApp Business Account. Meta ties this to policy violations or failed account verification.

What to do: Stop automated sends. Check Account Quality and any notification in WhatsApp Manager, then follow Meta's unlock or appeal steps. Retrying does not lift a lock.

What it means: Meta temporarily restricted the account or app because its systems or reviewers flagged policy violations such as spam reports, quality drops, or messaging-policy breaches.

What to do: Stop automated sends. Retrying during a block can make it worse. Check Account Quality in Meta Business Suite for the reason, appeal or wait out the restriction, then ramp volume back up slowly.

What it means: The template name does not exist for this WhatsApp Business Account in the language code you sent, or the template is not approved yet. Meta returns the same error for a pending or rejected template.

What to do: Check the exact template name and language code against WhatsApp Manager. They must match exactly, including locale suffixes such as en_US versus en. If the template is still in review, wait for approval before sending.

What it means: The number of variable parameters in your request does not match the number of variables in the template.

What to do: Count the {{1}}, {{2}} variables in the approved template and send exactly that many parameters in each component.

What it means: Meta paused this template because recipients reacted badly to it, so it cannot be sent until it is edited or replaced.

What to do: Stop sending the template. Edit it or create a new one with clearer value and a correct category, and send only to opted-in contacts.

What it means: The business phone number you send from is not registered with the Cloud API. It is typical right after a migration from the On-Premises API, or when registration never finished.

What to do: Finish the /register call for the phone number (or register again after the migration) in WhatsApp Manager or through the API, then retry. Every send from that number fails until registration completes.

What it means: The access token used for the Graph API call has expired, was revoked, or was invalidated, for example by a password change or removed app access ("Error validating access token: Session has expired").

What to do: Run the OAuth connection flow again for that channel. If many connections fail at once, check that your token refresh or health-check job is still running.

What it means: Meta rejected the send because the Page access token does not have the pages_messaging permission, or that permission was revoked (for example after a Page admin removed app access).

What to do: Reconnect the Page in Meta Business Suite and grant pages_messaging again during the OAuth flow. Retrying the same request does not help because the token itself lacks the scope.

What it means: The recipient cannot be reached on Messenger or Instagram for this send. Common reasons are that they blocked the Page, deactivated their account, or are otherwise unavailable.

What to do: Do not retry. Mark the conversation undeliverable and stop further automated sends to that contact.

What it means: Meta says the object with this ID does not exist, cannot be loaded because of missing permissions, or does not support the operation. In practice this appears when (1) the person-scoped ID (PSID) you are calling cannot be addressed from this Page token, or (2) a comment can no longer receive a private reply.

What to do: There is no fix for that specific ID and token pair, so log it and move on. To resolve a sender's name, call GET /{page_id}/conversations?fields=participants instead of GET /{psid}.

What it means: Your app's permission grant for this Page does not include the capability the endpoint needs. We have seen it on the per-user Profile API (GET /{psid}) for some Page tokens.

What to do: Reconnect through the correct OAuth flow for the platform so the app receives the full capability set, then retry. If the call is only for a sender's name, use the conversations endpoint instead.

What it means: You tried to hide a comment that is already hidden. It happens when two code paths, such as a webhook delivery and a retry job, act on the same comment.

What to do: Treat it as success. The comment is already hidden, so log it and move on.