WhatsApp error 131009 (parameter value is not valid): the values Meta rejects and how to correct them

WhatsApp error 131009 means Meta understood the shape of your request but did not like one of the values in it. Its error codes page describes the code as "One or more parameter values are invalid" and suggests two things: "See the endpoint's reference to determine which values are supported for each parameter, and see Phone Numbers to learn how to add a phone number to a WhatsApp Business account." So there are two families of causes: a value in the message body that breaks a rule, and a phone number or ID that is not set up the way the API expects. The message was not sent, and nothing was charged.

Missing versus invalid

Cloud API separates two mistakes that look alike in logs. If a required field is absent, you get error 131008. If the field is present but holds a value that is too long, in the wrong format, or simply not allowed, you get 131009. Knowing which one you have halves the search: for 131009, do not look for a gap, look for a value that breaks a limit.

Values that commonly trigger 131009

Character limits are the most frequent cause in production, because a label that fits in English often overflows in a longer translation, and nobody counts characters in the content team. See our guide to WhatsApp interactive messages for the full limits.

What the error looks like

Values and details text illustrative:

{
  "error": {
    "message": "(#131009) Parameter value is not valid",
    "type": "OAuthException",
    "code": 131009,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Button title length invalid. Min length: 1, Max length: 20"
    },
    "fbtrace_id": "Ax8Pq2LmZ4nRt6VbK0cYw1s"
  }
}

Meta's details text often names the field and even the limit. If it is vague, the trick below finds the bad value quickly.

Step-by-step fix

1. Read error_data.details. It usually names the field (button title, phone number, media ID).
2. Check the IDs before the content. Confirm the phone number ID in your URL belongs to the WhatsApp Business account your token can access, and that the number is registered. A wrong ID makes every message fail, whatever its content.
3. Measure every text against its limit. Count characters in button titles, list rows, section titles, header text and footers, including emoji and spaces.
4. Check media. Was the media ID uploaded by this same phone number, and less than 30 days ago? If not, upload again or send by link.
5. Check enum values such as type, recipient_type and interactive type against the reference: they are case-sensitive.
6. Bisect if still stuck. Send the smallest version of the message (just a text body), then add parts back one at a time until the error returns. The last part you added holds the bad value.

A failing reply-button block and its fix:

{
  "type": "button",
  "body": { "text": "Your table for 4 at 8:00 pm on Sat 8 Nov is ready to confirm." },
  "action": {
    "buttons": [
      { "type": "reply", "reply": { "id": "confirm", "title": "Yes, confirm my booking" } }
    ]
  }
}

{
  "type": "button",
  "body": { "text": "Your table for 4 at 8:00 pm on Sat 8 Nov is ready to confirm." },
  "action": {
    "buttons": [
      { "type": "reply", "reply": { "id": "confirm", "title": "Confirm booking" } },
      { "type": "reply", "reply": { "id": "change", "title": "Change time" } }
    ]
  }
}

A worked example

Arjun builds a booking bot for Spice Route, a restaurant in Bengaluru. The English version works. When the owner asks for a Hindi version, the reply button "बुकिंग की पुष्टि करें और टेबल रखें" goes out, and every Hindi booking message fails with 131009 while the English one keeps working. The details text names the button title. The Hindi label is over 20 characters.

He shortens it to "बुकिंग पक्की करें", adds a character check to the bot builder for every language, and moves the longer explanation into the message body, where the limit is far higher. The same week, a 131009 on images turns out to be a media ID uploaded five weeks earlier; his code now re-uploads media older than 25 days.

Preventing 131009

• Enforce limits where content is written. Show a character counter for button titles (20), list row titles (24), row descriptions (72) and header text (60).
• Normalise phone numbers on import to country code plus number, digits only. For India that is 91 followed by the 10-digit mobile number.
• Track media ID age and owner. Store which phone number uploaded each ID and when; refresh before 30 days.
• Keep phone number IDs in configuration, not code, and verify them against the account when a channel is connected.
• Test every language variant of an interactive message, not just the first one.

How Broadchat handles 131009

When a send fails with 131009, Broadchat shows the reason "A parameter value is not valid." on the failed message, along with Meta's own text so you can see which value was rejected. Media is handled for you: Broadchat uploads your files to Meta and caches the media IDs per phone number, and if Meta rejects a cached ID it drops it, uploads the file again and retries, falling back to sending the file by link. Text limits in your messages are still yours to respect, so check button and list labels when you build them.

Related reading: the WhatsApp API error codes cheat-sheet, error 131008 for missing fields and error 132001 for template name or language problems. New to the platform? Start with the plain-English guide to the WhatsApp Business API. Agencies can offer a WhatsApp chatbot builder under their own brand through the white-label program.