Error 131009 sits one step past error 131008. The field is there; its contents are not acceptable. Meta documents it as "Parameter value is not valid," with details reading "One or more parameter values are invalid," an HTTP status of 400, and a recommended action of checking the endpoint reference for supported values and learning how to add phone numbers to WhatsApp Business Accounts (Meta for Developers, WhatsApp error codes reference, retrieved 2026-08-20).
That second half of the recommended action is a strong hint about which invalid value Meta sees most: a phone number identifier that does not belong to the account making the request.
This guide covers the values that get rejected, how to tell 131009 apart from the codes it neighbours, and where to validate so it stops reaching Meta. For the wider failure surface, our WhatsApp Business API error codes reference indexes the rest.
What Gets Rejected
Field | Rejected because | Fix |
|---|---|---|
Phone number ID in the URL path | It is the display number, or belongs to a different WABA | Use the numeric phone number ID from the dashboard for the WABA you are sending from |
| Not E.164 — plus sign, spaces, hyphens, or a leading trunk zero | Country code plus subscriber number, digits only |
| A value outside the supported set for your API version | Use a documented message type |
| A locale the template does not exist in | Fetch the exact stored locale from the templates endpoint |
| Not one of the supported interactive types | Check the endpoint reference for your version |
Media | Expired, from a different number's upload, or from a failed upload | Re-upload and use the returned ID |
Media | Not publicly reachable, or wrong content type | Host it publicly with the correct MIME type |
Numeric fields sent as strings | Type coercion the API rejects | Send the type the reference specifies |
Two of these deserve a closer look because they account for most real traffic.
The phone number identifier
The send endpoint takes the phone number ID — a numeric identifier from the Meta dashboard — in the URL path:
POST https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}/messagesTwo distinct mistakes both produce 131009. Putting the actual phone number (919876543210) where the ID belongs is the first. The second, and the harder one to spot, is using a valid phone number ID that belongs to a different WhatsApp Business Account than the credentials you are authenticating with. The ID is well-formed and real, so nothing looks wrong.
This bites hardest for businesses running multiple numbers on one WhatsApp Business Account or several WABAs across brands, and during staging-to-production promotion where the staging ID survives in configuration. Meta pointing its recommended action at "how to add phone numbers to WABAs" is a hint that this is the frequent case.
Store the mapping between display number, phone number ID, and owning WABA explicitly in configuration, per environment. Do not let it live as a string literal in three services.
The recipient number
to expects E.164 without the plus: country code followed by subscriber number, digits only.
Value | Result |
|---|---|
| Accepted |
| Rejected |
| Rejected — trunk zero, no country code |
| Rejected |
A number malformed enough to be structurally invalid returns 131009 or error 100. A number that is well-formed but unreachable returns error 131026 instead. That distinction is a useful diagnostic: a validation error on the recipient field means the string is wrong, not the person.
Normalise at collection with a library such as libphonenumber rather than at send time, so one canonical value exists rather than every downstream system guessing.
Telling the Neighbouring Codes Apart
Four codes cluster around request validation and get conflated:
Code | Meaning | HTTP |
|---|---|---|
Invalid parameter — broad structural invalidity | 400 | |
Required parameter missing entirely | 400 | |
131009 | Parameter present, value not valid | 400 |
Template variable value formatted incorrectly | 400 |
The practical routine is the same for all four: read error_data.details in the response, which usually names the offending parameter, rather than branching on the code alone. If your logging captures only error.message, you have discarded the useful part — the same gap that makes error 100 feel undebuggable.
Where to Validate
At data collection, for anything customer-supplied. Phone numbers normalised to E.164 once, at the point of capture, with the country known. This removes the largest single source of rejected values and also prevents the 131026 delivery failures that malformed numbers cause downstream.
At configuration load, for identifiers. Phone number IDs and WABA IDs should be validated at startup against the account you authenticate as, not discovered to be wrong on the first send of a campaign.
At payload assembly, for enums. Constrain type, language.code, and interactive.type to a known set in your own code. An enum in your language beats a free-text string that Meta rejects after a network round trip.
Fetch template locales from the API. template.language.code must match the locale the template was actually created under — en and en_US are different templates with no fallback, which is also the dominant cause of error 132001. Cache the exact stored locale rather than hardcoding one.
Never retry. Like 131008, this is deterministic: the same value fails identically forever. Route to a dead-letter queue with the record identifier and the offending field, alert on volume, fix the source. Retrying at scale adds rate limit pressure on top of a defect you already have. Only genuine 500-class failures such as error 131000 belong in a retry loop.
Nothing was billed and no quality signal was generated, since the request was rejected at validation before a message existed.
Frequently Asked Questions
What does WhatsApp error 131009 mean?
Meta documents it as "Parameter value is not valid," with details stating one or more parameter values are invalid, returned with HTTP status 400. The field was present in your request but its contents were not acceptable. The recommended action is to check the endpoint reference for supported values, and Meta also links to guidance on adding phone numbers to WhatsApp Business Accounts.
What is the difference between error 131008 and 131009?
Absence versus contents. Error 131008 means a required parameter was missing from the request entirely. Error 131009 means the parameter was there but its value was rejected — a malformed recipient number, a phone number ID from a different account, an unsupported enum value, or an expired media ID.
Why does my phone number ID cause error 131009?
Two reasons. Either you put the actual phone number where the numeric phone number ID belongs in the URL path, or the ID is valid but belongs to a different WhatsApp Business Account than the credentials you are authenticating with. The second is harder to spot because the identifier looks entirely correct. Meta's own recommended action points at adding phone numbers to WABAs, which suggests this is the common case.
How should recipient numbers be formatted?
E.164 without the plus sign: country code followed by the subscriber number, digits only. No spaces, hyphens, parentheses, or leading trunk zero. Normalise at the point of collection using a library such as libphonenumber, with the subscriber's country known, so one canonical value exists across every downstream system.
Should I retry after error 131009?
No. The same value will be rejected identically on every attempt, so retrying only consumes rate limit budget. Send the message to a dead-letter queue with the record identifier and the offending field name, alert on volume, and fix the value at its source. Retries belong on 500-class failures such as error 131000.
Fix the Value at Its Source
Error 131009 is never interesting, which is precisely the argument for eliminating it in code rather than diagnosing it repeatedly. Meta names the offending parameter in error_data.details; the reason the error feels vague is almost always a logging pipeline that keeps only the top-level message.
The durable fixes sit upstream of the send. Normalise phone numbers once at collection. Validate phone number IDs against the authenticating account at startup. Constrain enum fields in your own types. Fetch template locales from the API instead of hardcoding them. Each removes a category of rejected value permanently rather than one message at a time.
Want value validation before the request leaves your stack? Helo.ai is a Meta Partner with 25 years of enterprise communication experience, validating recipient formats, identifiers, and template locales against live account data before send. Talk to an expert.
Next: error 131008 if the field is missing rather than wrong, or error 131026 if the number is well-formed but messages still fail.
