WhatsApp Cloud API error corpus

17 Meta WhatsApp Cloud API error codes with the handling decision each one implies — not just what the code means, but what a sender should actually do with it.

Every WhatsApp vendor publishes a page explaining what an error code means. We could not find one that publishes what to do with it, which is the part that costs money to learn.

The reason this exists

130429, 131048 and 131056 are throughput caps. Meta returns them as HTTP 4xx, not 429.

A client implementing the ordinary rule — 4xx is a client error, do not retry; 429 and 5xx are transient — will permanently fail every message caught by a cap that would have cleared on its own within the hour. On a broadcast that silently discards the tail while the front half delivers, so it reads as a partial-delivery bug rather than a rate limit. Nothing in the response body says "cap".

The full write-up.

Install

npm i whatsapp-cloud-api-error-corpus

import { findCode, isRetryable, RATE_LIMIT_CODES } from 'whatsapp-cloud-api-error-corpus';

isRetryable(131056);        // true  — pair rate limit, arrives as 400
isRetryable(132001);        // false — template does not exist
isRetryable(999999);        // undefined — not documented, decide for yourself
findCode(190).handling;     // { accountLevel: true, ... }

Or fetch it directly, no install, CORS open:

curl https://www.tryklaros.com/whatsapp-api-errors.json

The codes

| Code | HTTP | Meaning | Handling | |---|---|---|---| | 100 | 400 | Invalid parameter | fail | | 190 | 401 | Access token expired or invalid | account | | 130429 | 400 | Rate limit hit | retry, cap | | 131008 | 400 | Required parameter missing | fail | | 131009 | 400 | Parameter value not valid | fail | | 131026 | 400 | Message undeliverable | suppress | | 131030 | 400 | Recipient not in allowed list | fail | | 131047 | 400 | Re-engagement message required | template | | 131048 | 400 | Spam rate limit hit | retry, cap | | 131049 | 400 | Per-user marketing cap reached | fail | | 131051 | 400 | Unsupported message type | template | | 131056 | 400 | Pair rate limit hit | retry, cap | | 132000 | 400 | Template parameter count mismatch | fail | | 132001 | 400 | Template does not exist | fail | | 132005 | 400 | Template hydrated text too long | fail | | 132007 | 400 | Template format or character policy violation | fail | | 133010 | 400 | Sending number not registered | account |

fail means permanent for that message: fix the request, do not retry it unchanged.

How this is maintained

The handling flags are generated, not hand-written. They come from running the same classifyWaError function that runs on Klaros's production send path, against a synthetic response for each code. The dataset therefore cannot describe behaviour the software does not have.

This repository is built output. It is regenerated from source and pushed; edits made here are overwritten. Corrections are welcome as issues, and they get fixed at the source.

Verified against Meta Graph API v25.0.

Licence

CC-BY-4.0. Use it freely, including commercially. Attribution to Klaros is appreciated and required by the licence.

Klaros is an independent product and is not affiliated with, endorsed by, or sponsored by Meta. WhatsApp is a trademark of Meta Platforms, Inc.