WhatsApp Cloud API
WhatsApp API error codes, and what to do about each
All 86 error codes Meta documents for the WhatsApp Cloud API, grouped by what went wrong. Each one links to a page with its causes, fixes and retry advice.
How a WhatsApp error reaches you through InfiQ
InfiQ passes Meta's error through unchanged, so the codes on this page are the codes you see. If Meta refuses a send straight away, the API response carries Meta's error object (code, message, error_data.details, fbtrace_id) together with an InfiQ_traceid. If Meta accepts the message and it fails later, InfiQ posts a message.failed webhook with the Meta code in metaErrorCode. Keep both trace IDs with the failed message: Meta's support uses the fbtrace_id, InfiQ's support the InfiQ_traceid.
Sending and delivery
The request was malformed, or WhatsApp accepted it and couldn't deliver it.
- 100Invalid parameter: unsupported or misspelled field
- 131008A required parameter is missing
- 131009A parameter value isn't valid
- 131021Sender and recipient are the same number
- 131026Message undeliverable to this recipient
- 13104724-hour window closed; send a template
- 131049Marketing message held back for healthy engagement
- 131050Recipient stopped marketing messages from you
- 130403Your business has blocked this user
- 130472Not sent: part of a marketing message experiment
- 131051Unsupported message type
- 131052Couldn't download media the user sent
- 131053Couldn't process the media in your message
- 135000Unknown error in the request parameters
Template sends
The template message didn't match an approved, healthy template.
- 132000Wrong number of template parameters
- 132001Template doesn't exist in that language, or isn't approved
- 132005Template text too long once filled in
- 132007Template content violates a WhatsApp policy
- 132012Template parameter in the wrong format
- 132015Template paused for low quality
- 132016Template disabled after repeated pauses
- 132068Flow is blocked
- 132069Flow is throttled: 10 sends in the last hour
Rate limits
Too many calls or messages in a window, or a quality-based cap.
- 4The app reached its API call rate limit
- 80007The WhatsApp Business Account reached its rate limit
- 130429Message throughput limit reached
- 131048Spam rate limit on your number
- 131056Too many messages to the same person
- 131064Messaging limited for template category violations
- 133016Too many registration attempts for the number
Account, billing and policy
The WhatsApp Business Account can't send until something on it is fixed.
- 368Account restricted or disabled for a policy violation
- 130497Can't message users in this country
- 131031Account locked, or request data doesn't match
- 131037555 number has no approved display name
- 131042Problem with the account's payment method
- 131045Sending number has a registration error
- 131057Account in maintenance mode
- 131063Marketing templates disabled on Cloud API
- 134011WhatsApp Payments terms not accepted yet
- 33The business phone number was deleted
Authorisation
The token or the app's permissions don't allow the call.
Phone number registration
The business number isn't registered, or registration was refused.
- 133000A previous deregistration attempt failed
- 133005Two-step verification PIN incorrect
- 133006Verify the number before registering it
- 133008Too many two-step PIN guesses
- 133009Two-step PIN entered too quickly
- 133010Number not registered on the platform
- 133015Number recently deleted; deletion not finished
Creating and managing templates
Meta rejected a template you tried to create or edit.
- 2388019Template limit for the account reached
- 2388039Template status can't be changed
- 2388040A template field is over its character limit
- 2388047Template header format is incorrect
- 2388072Template body format is incorrect
- 2388073Template footer format is incorrect
- 2388293Too many variables for the template's length
- 2388299Variables at the start or end aren't allowed
- 200005Template insights not available yet
- 200006Template insights can't be disabled
- 200007Template insights not enabled
Number migration and onboarding
Moving a number or onboarding a business didn't go through.
- 2388012Number is already in your account
- 2388091Number isn't being migrated; register and verify it
- 2388093Number isn't being migrated, so its code can't be verified
- 2388103Number can't be migrated (several reasons)
- 2494100Business number in maintenance mode
- 2593079Account already marked for migration to another solution
- 2593085Account not eligible for ownership transfer
- 2593107Contact or history sync already used for this number
- 2593108Sync only allowed within 24 hours of onboarding
- 1752041Business already invited to onboard by a partner
Marketing Messages API
Codes Meta documents for sending marketing templates through its Marketing Messages API.
Meta service errors
Something failed on Meta's side; usually temporary.
Source: Meta's WhatsApp error codes reference, checked 21 November 2026. Section headings (Sending and delivery, Rate limits and so on) are InfiQ's grouping, not Meta's.
FAQ
Frequently asked questions
Where do WhatsApp API error codes come from?
They are Meta's codes for the WhatsApp Business Platform. Each error carries a numeric code, a message such as "(#130429) Rate limit hit", a details text with the likely reason and an fbtrace_id. Build your handling around the code and the details, not the HTTP status.
Which WhatsApp errors should I retry?
Retry temporary ones with backoff: rate limits such as 130429 and 131056, and Meta service errors such as 131000 and 131016. Don't retry delivery refusals such as 131050 or 130403, and fix the request first for errors like 131008, 131009 or 132001.
Why do some WhatsApp errors arrive in a webhook instead of the API response?
Meta checks some things only at delivery time. The send is accepted and returns a message ID, and the failure comes later as a failed status. Through InfiQ that arrives as a message.failed webhook with the Meta code in metaErrorCode.
Are error subcodes still returned?
Meta has deprecated error_subcode and says it is not returned from Graph API v16.0 onwards. Use the code and the details text instead.
Send WhatsApp messages with errors you can act on.
InfiQ's API returns Meta's codes with a trace ID and posts every delivery failure to your webhook, so nothing fails silently.
