WhatsApp error 131000 ("Something went wrong"): how to debug an unknown Cloud API error

WhatsApp error 131000 is the Cloud API's catch-all code: Meta's error reference describes it as "Message failed to send due to an unknown error." Its listed fix is short: "Try again. If the error persists, open a Direct Support ticket." In other words, Meta could not or did not classify the failure. Your token was accepted and the request reached WhatsApp, but something went wrong while processing it. Most of the time a careful retry is enough. When it is not, the job is to find the pattern so that you can either fix your request or give Meta support the evidence it needs.

What the error looks like

131000 can arrive in the HTTP response to your send request or later in a statuses webhook with status: failed. Meta's error page notes that Cloud API errors are returned synchronously, asynchronously via webhook, or sometimes both, so monitor both. A synchronous response looks like this (values are illustrative):

{
  "error": {
    "message": "(#131000) Something went wrong",
    "type": "OAuthException",
    "code": 131000,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Something went wrong"
    },
    "fbtrace_id": "AbC1dEfGh2IjKlMn3OpQrSt"
  }
}

Meta recommends building error handling on the numeric code and the details text, not on the title inside message, because titles will eventually be deprecated. With 131000 the details field is often no more helpful than the title, which is exactly why the code is hard to debug. The fbtrace_id is the one field that matters for support: Meta describes it as a trace ID you can include when contacting Direct Support.

Transient blip or real fault? A triage table

Because the code itself tells you little, the useful signal is how often it appears and what the failed sends have in common:

Two related codes are easy to confuse with 131000. 131016 means "A service is temporarily unavailable", and Meta's fix is to check the platform status page before trying again. 135000 means the message failed because of "an unknown error with your request parameters", which points at your request syntax rather than at Meta. If you see either, follow its own advice. The WhatsApp API error codes cheat-sheet lists both next to their neighbours.

Step-by-step fix

1. Retry the same request with back-off. Wait a few seconds, then try again, doubling the delay each time (for example 5, 10, 20 and 40 seconds) and stopping after four or five attempts. Retrying instantly in a loop adds load and rarely helps.
2. Check the status page. If many unrelated sends are failing at the same moment, look at the WhatsApp Business Platform Status page before you change any code.
3. Isolate the request. Send the same template to your own test number, then a simple text message inside an open customer service window, then the same template without the media header. Whichever variation fails tells you where to look.
4. Compare with Meta's reference. Rebuild the failing request from the example in Meta's send-message reference and add your fields back one at a time. A field in an unexpected shape sometimes surfaces as an unknown error rather than as 131008 or 131009.
5. Open a Direct Support ticket if it persists. Meta links Direct Support from the error row. Give support everything listed in the next section.

What to put in a Direct Support ticket

A ticket that says "we get 131000" usually comes back with a request for details. Save a round trip by sending all of this at once:

• the fbtrace_id of at least two or three failed requests
• the phone number ID and the WhatsApp Business account ID you sent from
• the exact time in UTC of each failure
• the full request body, with the access token removed
• the message ID (wamid) if the failure came through a status webhook
• what you already ruled out: other templates, other recipients, other media, and whether the status page showed an incident

Log these fields automatically for every failed send so you are not reconstructing them from memory a day later.

A worked example

Arjun maintains the order system for Rangoli Home, a home-decor brand in Jaipur. On a Tuesday evening his logs show 131000 on every order_shipped template send, while the order_confirmed template keeps working. The two templates differ in one way: order_shipped has a document header with the invoice PDF, served from the brand's storage bucket.

Retrying with back-off does not help, so he isolates the request. The same template with a different, small test PDF goes through. The real invoices, generated by a new PDF library deployed that afternoon, fail. He rolls the PDF change back, the sends recover, and he files the failing traces with Meta's support anyway, because an unsupported file should ideally have returned a media error such as 131053 rather than an unknown one. The lesson is the order of operations: retry, isolate, change one thing, and only then escalate.

Handling 131000 in code

Treat 131000 as retryable, but not forever. A sensible policy:

const RETRYABLE = new Set([131000, 131016, 130429, 131056]);

async function sendWithRetry(send: () => Promise<Response>, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const res = await send();
    const body = await res.json();
    const code = body?.error?.code;
    if (!code) return body;                          // accepted
    if (!RETRYABLE.has(code) || attempt >= maxAttempts) {
      logFailure(code, body.error.fbtrace_id);       // keep the trace for support
      throw new Error(body.error.message);
    }
    await sleep(5000 * 2 ** (attempt - 1));          // 5s, 10s, 20s, 40s
  }
}

Two cautions. First, retry only requests that clearly failed; if a request timed out with no response at all, check your logs and webhooks for a message ID before resending, or you may send the same message twice. Second, keep a ceiling on how many messages are waiting for a retry, so that a Meta incident does not turn into a backlog that floods customers when it ends.

131000 in WhatsApp Flows

The same code appears outside messaging. Meta's error reference notes that for WhatsApp Flows with an endpoint, 131000 is returned when setting the business public key fails, because Meta could not calculate the signature or its internal endpoint returned an error. If you see 131000 while uploading your Flows public key, retry later and confirm the key is a valid 2048-bit RSA public key in PEM format, which Meta lists as a requirement for the related parameter error.

How Broadchat shows 131000

When a message sent from the Broadchat panel fails with 131000, the reason shown with the message is "Something went wrong on Meta's side. Try again.", and Message info shows Meta's error code. If you send through a channel's access token and API URL (the Graph-compatible channel API), Broadchat passes Meta's response back to you unchanged and does not retry for you, so your own code owns the retry policy described above. A template that fails at Meta is not charged to the channel wallet: the reserved amount is refunded.

For the background on how the Cloud API fits together, see the plain-English guide to the WhatsApp Business API. Agencies that run integrations for several clients can offer the same logs, failure reasons and wallets under their own brand through the white-label program.