A WhatsApp API error code tells you exactly why a message failed. The most common are 131049 (Meta held a marketing message), 131047 (24-hour window closed) and 131026 (number cannot receive). Find your code below for the meaning and the fix.
Meaning: Meta held back a marketing template to keep engagement healthy. The person already got many marketing messages recently, or your messages get low engagement.
Fix: Do not retry for at least 24 hours. Send to recently engaged users, improve relevance, and move transactional content to utility templates.
Full guideMeaning: The number is not on WhatsApp, the user has an old app version, has not accepted the latest terms, or has blocked you.
Fix: Check the number has a country code and WhatsApp. Remove numbers that fail repeatedly. Do not retry in a loop.
Full guideMeaning: More than 24 hours passed since the customer last messaged you, so free-form messages are not allowed.
Fix: Send an approved template instead. Once the customer replies, the 24-hour window opens again.
Full guideMeaning: The customer turned off marketing messages from your business in WhatsApp.
Fix: Stop marketing sends to this number. Utility and service messages are still allowed.
Meaning: Too many messages to the same number in a short time.
Fix: Wait before sending to that number again and combine messages into one.
Meaning: You exceeded the number's throughput (about 80 messages per second by default).
Fix: Queue sends and retry with exponential backoff.
Full guideMeaning: Too many recipients blocked or reported your messages, so Meta limited sends from the number.
Fix: Pause marketing, clean the list to opted-in users only, and check quality rating in WhatsApp Manager.
Full guideMeaning: You tried to send a message to your own business number.
Fix: Use a different test number.
Meaning: The number of variables sent does not match the template.
Fix: Send exactly one value per {{n}} variable, in the header, body and buttons.
Full guideMeaning: A required field is empty, often a blank template variable from a CSV column.
Fix: Fill every variable with a non-empty value before sending.
Full guideMeaning: A value has the wrong format, such as a bad phone number, URL or button payload.
Fix: Check the value against the template and the API format, then resend.
Meaning: The template name or language code does not match an approved template on this WABA.
Fix: Use the exact name and language (for example en or en_US) shown in WhatsApp Manager.
Meaning: After filling variables, the text exceeds the character limit.
Fix: Shorten variable values. The body limit is 1,024 characters.
Full guideMeaning: Variable content breaks WhatsApp policy or formatting rules.
Fix: Remove new lines, tabs or more than 4 spaces in a row from variable values.
Meaning: A variable type does not match, for example text sent where the template expects media.
Fix: Send the parameter type the template defines (text, currency, date-time, image, document).
Meaning: The template got too many blocks or reports and was paused.
Fix: Edit the copy, target engaged users, and wait for the pause to end.
Full guideMeaning: The template was paused too many times and is now permanently disabled.
Fix: Create a new template with different, more relevant copy.
Full guideMeaning: Meta could not charge the payment method on the WhatsApp account, or there is an unpaid amount.
Fix: Settle the amount or add a valid payment method in Business Settings, then send a real test.
Full guideMeaning: The account was locked for a policy violation or failed two-step verification.
Fix: Check Account quality in WhatsApp Manager and request a review.
Full guideMeaning: The account is restricted from sending because of policy violations.
Fix: Read the violation in WhatsApp Manager, fix the cause and appeal.
Full guideMeaning: The number was added to the WABA but is not registered on the Cloud API.
Fix: Register the number with the API using its two-step verification PIN.
Full guideMeaning: The PIN sent during registration is wrong.
Fix: Reset the PIN in WhatsApp Manager and register again.
Full guideMeaning: The account is being updated, for example during a throughput upgrade.
Fix: Wait a few minutes and retry.
Meaning: The token used to call the API expired or was revoked (for example after a password change).
Fix: Generate a new token. Use a System User token so it does not expire.
Meaning: The request has a wrong or unsupported field, or the token lacks access to that object.
Fix: Read the error message details; it names the field. Reconnect the account if the token scope is stale.
Meaning: The app does not have whatsapp_business_messaging or whatsapp_business_management permission for this WABA.
Fix: Grant the permission to the System User and re-generate the token.
Meaning: The customer's media could not be downloaded, usually because the link expired.
Fix: Download inbound media as soon as the webhook arrives.
Meaning: The file type is not supported or the file is too large.
Fix: Use a supported type within the size limit (image 5 MB, video 16 MB, document 100 MB).
Full guideMeaning: A temporary error on Meta's side.
Fix: Retry with backoff. If it continues, check the WhatsApp Business API status page.
See all WhatsApp API problems by symptom, read our error codes deep dive, or send us the code and we will tell you the fix.