wasender.dev

Error reference

Every error the API can return, what causes it, and what to do about it. If you arrived from the href in an error response, the relevant section is already open below.

The shape of every error

Every failure on every endpoint returns the same envelope, so you only parse this once:

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "These limits protect the number from being restricted by WhatsApp.",
    "href": "https://docs.wasender.dev/errors#rate-limit",
    "support": "[email protected]"
  }
}

code matches the HTTP status. details is present when there is something specific to say. href links to the section on this page for that error, which is how you got here.

400

Bad request

Not retryable

When you see it

The request body or query string did not validate. The details field names the specific problem.

What to do

Read details, which identifies the offending field. The most common causes are a recipient in the wrong format, a missing required property, and sending form data where JSON was expected.

401

Missing or invalid channel token

Not retryable

When you see it

The token was absent, malformed, revoked, or belongs to a channel that no longer exists.

What to do

Send the whole token as Authorization: Bearer wsk_…, or as ?token=wsk_… if you cannot set headers. Tokens are shown once at creation and can be rotated from the dashboard. A truncated paste and a stray trailing space are the two usual causes.

402

Channel is not currently billable

Not retryable

When you see it

The subscription is past due, or the free tier allowance of one connected number was exceeded.

What to do

Open billing in the dashboard. Your WhatsApp session is retained while this is resolved, so you do not have to scan a QR code again after paying.

403

Not permitted

Not retryable

When you see it

The action is understood but not allowed for this channel. Group operations needing admin rights are the usual case.

What to do

Check that the connected number actually holds the permission, for example that it is an admin of the group you are trying to modify.

404

Not found

Not retryable

When you see it

The chat, message, contact, group or media id does not exist, or is not visible to this channel.

What to do

Ids are scoped to the connected number. A message id from one channel means nothing to another. Confirm the id came from this channel and has not been deleted.

413

File exceeds the size limit

Not retryable

When you see it

An uploaded file is larger than the limit for its media type.

What to do

Compress or re-encode before uploading. WhatsApp itself caps media size, so a smaller file is required rather than merely preferable.

429

Rate limit exceeded

Retryable

When you see it

Too many requests in the window. The limits exist to keep WhatsApp from restricting the number, not to sell you a larger plan.

What to do

Back off for the period in the Retry-After header, then continue. Spread bulk sends over time rather than firing them in a burst. Retrying immediately makes it worse and puts the number at risk.

501

Endpoint not implemented

Not retryable

When you see it

The path exists in the broader API surface we track but is not built yet. The message names the endpoint.

What to do

Nothing to fix in your code. Email [email protected] with the endpoint and it gets prioritised. This status is deliberate so you find the gap during development instead of in production.

502

Upstream session runtime error

Retryable

When you see it

The session runtime behind your channel returned an error we could not translate into something more specific.

What to do

Retry once with backoff. If it persists, send us the request id from the response headers and we can trace it.

503

Channel is not connected

Retryable

When you see it

The WhatsApp session is reconnecting, waking from hibernation, or its shard is redeploying. This is expected occasionally and is not an outage.

What to do

Retry with exponential backoff. This is the one status worth building a retry path for, because it is normally transient and resolves without any action from you. Poll GET /health if you want to confirm the session state.

Retrying safely

Three of these are worth a retry path: 429, 502 and 503. Everything else means the request itself needs changing, and repeating it unchanged will fail the same way.

For 429, wait for the period in the Retry-After header rather than guessing. For 503, use exponential backoff: the session is usually reconnecting and recovers on its own.

One thing that is not an error: a 2xx means WhatsApp accepted the message, not that it was delivered. WhatsApp does not reject an unreachable recipient synchronously. Confirm real delivery through webhooks or GET /statuses/{MessageID}.