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, or is not yours.	Check the channelId.
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

The hard limits are Meta’s, not ours, and 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.