Errors and limits

Errors are JSON and always carry a message you can log:

{ "statusCode": 402, "error": "Payment Required", "message": "Insufficient balance" }

Status codes

Code	Meaning	What to do
400	The payload is malformed or a field is missing.	Fix the request. Retrying will not help.
401	Missing or invalid API key.	Check the x-neike-api-key header.
402	Not enough balance in your Neike wallet.	Top up in the console. Nothing was queued. This is not Meta’s billing — see below.
403	The key is valid but lacks the required scope.	Issue a key with the scope the endpoint declares.
404	The channel does not exist, is not yours, is inactive, or has no credentials.	Check the channelId. An inactive or credential-less channel also returns 404: its status is shown in the channel list in the console.
409	The resource already exists.	Treat as success if you are retrying.
5xx	Our problem.	Retry with backoff.

Only 5xx and network failures are worth retrying automatically. Everything in the 4xx range is a request you need to change.

The two payments

A 402 is about the Neike wallet: what you pay us for the service. It is the only payment this API can see, which makes it easy to assume that a funded wallet means you can send. It does not.

Meta bills you separately for the messages themselves, against your own WhatsApp Business Account. Neike is a technical provider: we never pay that for you and cannot add a payment method on your behalf. If it is missing, requests still return 202 — we accepted them — and Meta fails the delivery afterwards with error 131042, “Business eligibility payment issue”.

Add it on your WhatsApp Business Account, following Meta’s guide. The console flags a channel when it detects the account has none.

Failures after a 202

A send that was accepted can still fail at Meta — an invalid number, a closed 24-hour window, a rejected template, a missing payment method on your Meta account. That never comes back as an HTTP error, because the HTTP call already finished. It arrives as a status webhook with failed and the reason Meta gave.

The ones you will actually hit:

Meta code	What it means	What to do
131042	Business eligibility payment issue: something is wrong with your payment method at Meta.	Add or fix the payment method on your WhatsApp Business Account. Retrying changes nothing.
131047	More than 24 hours passed since the contact last replied.	Send an approved template instead of free-form text.
131026	Undeliverable: the number may not be on WhatsApp, or has not accepted Meta’s terms.	Check the recipient. Do not retry.
132001	The template does not exist in that language, or is not approved yet.	Check the name, language and status in the console.
130429	Cloud API throughput limit reached.	Slow down and retry.

The console translates these in Deliveries and keeps Meta’s original text next to the translation. The full list is Meta’s error code reference.

Every attempt is recorded, so a delivery that failed on your side can be replayed from the console rather than resent by hand.

Rate limits

There are two kinds of limits, and both answer with 429.

Neike’s request limit. Every API key has a request quota per minute, and so does your whole account (all its keys together). When you exceed it, Neike answers 429 with a Retry-After header holding the seconds to wait. Wait that long, then retry, and back off if it keeps happening. The quota is a fixed window, so a burst of up to twice the limit can land around the moment the window resets. Routes that are free and synchronous, such as POST /api/messages/typing (it calls Meta during the request and is not billed), have their own lower quota. The same limits apply to the MCP endpoint (/mcp). Console sessions are not limited. The default values are 600 requests per minute per key and 1200 per account, and 120 and 240 for typing.

Meta’s limits. They depend on your channel’s quality rating and messaging tier, both visible per channel in the console. Sending faster than your tier allows gets throttled at Meta and lowers the rating. A 429 from Meta carries Meta’s original text in the message and has no Retry-After header, which is how you tell the two apart.