API v1 errors

A field in the request is missing, has the wrong type, or breaks a rule. Nothing was sent or saved.

Fix: Read param for the field and fix it, then retry. The same Idempotency-Key may be reused, because a request that failed validation is not stored.

to is not an E.164 phone number, a Business-Scoped User ID (such as US.13491208655302741918), or a WhatsApp username starting with @.

Fix: Send the phone in international form (+5491155550000), the contact's wa_user_id, or @username. To reply in an existing chat, send conversation_id instead.

The template needs a value the request does not set, so the message was not sent.

Fix: Read GET /v1/templates/{id} for the variables this template needs, and set every required one in template.variables.

The cursor is not one this API issued, or it is older than 24 hours.

Fix: Start the list again without a cursor, then follow next_cursor from each page.

A message to an existing conversation always leaves from that conversation's number, and from names a different one.

Fix: Leave from out when you send conversation_id, or send to instead to choose the number yourself.

The file is larger than this use of it allows. An upload to POST /v1/media takes up to 100 MB; a send takes WhatsApp's limit for its type: 5 MB for an image, 16 MB for audio and video, 100 MB for a document, 500 KB for a sticker. An AI bot's files have the dashboard's limits.

Fix: Use a smaller file. For a send, a document allows the largest size, so a large image or video can go out as a document. param names the file that is too large.

The file is not of a type this endpoint accepts. The type is read from the file's content, not from its name or the declared content type.

Fix: Convert the file to a supported type, such as JPEG or PNG for an image, MP4 for a video, or PDF for a document, and upload it again.

The request carries no API key.

Fix: Send the key in the Authorization header: Authorization: Bearer nfy_live_.... Create a key in Settings, API.

The API key is not one Whatsable knows, or it has been revoked.

Fix: Copy a current key from Settings, API and send it as Authorization: Bearer <key>.

The key was sent in the query string, in the body, or in the Authorization header without Bearer. v1 reads it only as a Bearer token, because a key in a URL ends up in logs it can never be removed from.

Fix: Move the key to the Authorization header as Authorization: Bearer <key>. If the key was ever in a URL, revoke it in Settings, API and create a new one.

This key was imported from the previous Whatsable system. It still works on the old endpoints, and v1 does not accept it.

Fix: Create a new key in Settings, API and use it with v1.

This access token does not belong to a live WhatsAble connection. It has expired, the connection was revoked in Settings, API, or the person who connected it is no longer an owner or admin of the organization.

Fix: Refresh the token, or connect WhatsAble again from your AI client. An owner or admin of the organization must approve the new connection.

This key is not allowed to call this endpoint. The scope it needs is in details.required_scope.

Fix: Create a key with the scope this endpoint needs in Settings, API, or use a key with Full access.

The number named in the request is not one this key may use.

Fix: Send from one of this key's numbers (GET /v1/me lists them), or add the number to the key in Settings, API.

This organization has no active Whatsable subscription, so the API answers only GET /v1/me.

Fix: Start or renew a plan in Settings, Billing, then retry.

The organization's plan does not include this part of Whatsable.

Fix: Upgrade the plan in Settings, Billing, then retry.

This organization is still being moved to Whatsable's new platform, so it cannot send or create templates here yet. Reads work.

Fix: Keep sending through your current integration until Whatsable tells you the move is finished.

The organization has more WhatsApp numbers than its plan includes, and this number is one of the numbers above that count. It still receives messages, and it sends nothing.

Fix: This number is over the plan. Ask the owner to add it to the plan in Settings, Business numbers, or to disconnect another number. You can also send from another number of the organization.

No number with this id or phone exists in the organization, or this key may not see it.

Fix: List the numbers this key may use with GET /v1/numbers and use one of their ids.

No template with this id, or with this name and language, exists on the WhatsApp Business Accounts of this key's numbers.

Fix: List templates with GET /v1/templates and send one of their ids, or the exact name and language.

No contact with this id exists in the organization. A WhatsApp username reaches only a contact who has already written to you.

Fix: Check the id with GET /v1/contacts, or address the person by phone number instead of username.

No conversation with this id exists, or it is on a number this key may not use.

Fix: Check the id, or address the person with to instead. A key sees only conversations on its own numbers.

No message with this id exists, or it belongs to a number this key may not see.

Fix: Check the id. A key reads only messages on its own numbers.

No label with this id or name exists in the organization. The API never creates a label as a side effect.

Fix: List labels with GET /v1/labels, or create the label first with POST /v1/labels.

No media file exists at this link, or the link expired. Media links are valid for 15 minutes.

Fix: Read the message again with GET /v1/messages/{id} for a fresh media.url, and download it straight away.

No v1 endpoint answers this method and path.

Fix: Check the method and path against the API reference at https://api.whatsable.app/v1/openapi.json.

No scheduled message with this id exists, or it is on a number this key may not use.

Fix: Check the id with GET /v1/scheduled-messages. A key sees only scheduled messages on its own numbers.

No broadcast with this id exists, or it sends from a number this key may not use.

Fix: Check the id with GET /v1/broadcasts. A key sees only broadcasts from its own numbers.

No AI bot with this id exists in the organization.

Fix: List the organization's bots with GET /v1/ai-bots and use one of their ids.

This AI bot has no knowledge file with this id.

Fix: List the bot's knowledge files with GET /v1/ai-bots/{id}/knowledge-files and use one of their ids.

This AI bot has no sendable file with this id.

Fix: List the bot's files with GET /v1/ai-bots/{id}/files and use one of their ids.

This Idempotency-Key was already used in the last 24 hours with a different request body.

Fix: Use a new Idempotency-Key for a different request. Reuse a key only to retry the exact same request.

A request with this Idempotency-Key is still being processed.

Fix: Wait the seconds in Retry-After and retry with the same key. You will get the first request's answer.

A template with this name and language already exists on this WhatsApp Business Account.

Fix: Choose another name, or use the existing template (GET /v1/templates?name=...).

A label with this name already exists in the organization. Names are compared ignoring case and accents.

Fix: Choose another name, or use the existing label (GET /v1/labels).

Another AI bot in the organization already has this name.

Fix: Choose another name, or change the existing bot (GET /v1/ai-bots).

The If-Match header names a version that is no longer current: the resource changed after you read it. Nothing was written.

Fix: Read the resource again, reapply your change to what it holds now, and send it with the new ETag as If-Match.

This is a session message, and the person has not written to this number in the last 24 hours, or never has, so WhatsApp would refuse it. Nothing was sent.

Fix: Send an approved template instead (type: template), or wait until the person writes to this number again.

Meta has not approved this template (it is pending, rejected, paused or disabled), so it cannot be sent.

Fix: Wait for Meta's review (GET /v1/templates/{id} shows its status), or send an approved template.

The template belongs to a different WhatsApp Business Account than the number this send leaves from.

Fix: Send from a number on the template's account with from, or pick a template of the sending number's account with GET /v1/templates?number_id=<id>.

This template uses named variables ({{customer_name}}), which the API cannot send yet. WhatsApp was not called.

Fix: Send a template with numbered variables ({{1}}, {{2}}) instead. A broadcast also refuses an authentication template and one with a coupon-code button, which message says: send those one at a time with POST /v1/messages.

WhatsApp refused to accept this template for review, so no template was created. Meta's error code is in details.meta_code.

Fix: Change the template (often its name, wording, or examples) and submit it again. A template Meta accepts and later rejects in review is not this error: it reads as status rejected.

The number this request would send from is paused, disconnected, or still being registered. The API never switches to another number on its own.

Fix: Resume or reconnect the number in Settings, or send from another number with from.

This contact has neither a phone number nor a WhatsApp user id, so there is nothing to send to.

Fix: Add the contact's phone number, or wait until the person writes to you.

The organization already has the most labels it may have.

Fix: Delete a label you no longer use (DELETE /v1/labels/{id}), then retry.

The free plan can message 2 contacts, and this send would reach a new one.

Fix: Subscribe in Settings, Billing, then retry. A reply to a contact already messaged still sends.

The organization already has the most AI bots it may have.

Fix: Archive and delete a bot you no longer use (PATCH /v1/ai-bots/{id} with status archived, then DELETE /v1/ai-bots/{id}), then retry.

Only a pending scheduled message can be cancelled. This one is being sent right now, or has already been sent, suppressed, failed, missed or cancelled.

Fix: Read it with GET /v1/scheduled-messages/{id} for its status. One that was sent carries message_id, the Message it became.

This broadcast is completed or already cancelled, so there is nothing left to cancel.

Fix: Nothing to undo: read GET /v1/broadcasts/{id} for what it sent.

Only an archived AI bot can be deleted, so that deleting a bot is always a deliberate second step.

Fix: Archive it first with PATCH /v1/ai-bots/{id} and {"status": "archived"}, then delete it.

This AI bot is archived, so it cannot answer on a number or a conversation, and it takes no new knowledge files or sendable files.

Fix: Choose another bot, or bring this one back with PATCH /v1/ai-bots/{id} and {"status": "active"} or {"status": "draft"}.

This AI bot already holds the most sendable files it may have.

Fix: Delete a file the bot no longer needs (DELETE /v1/ai-bots/{id}/files/{file_id}), then retry.

The label is limited to other numbers, so it cannot be used with the number this request names.

Fix: Use a label available on this number (GET /v1/labels shows each label's number_ids), or add the number to the label with PATCH /v1/labels/{id}.

This API key made more requests than its rate limit allows, or the sending number reached its per-second send limit. The request was not processed.

Fix: Wait the seconds in Retry-After, then retry. Spread requests out; RateLimit-Remaining shows what is left of the key's budget.

Something went wrong on Whatsable's side.

Fix: Contact Whatsable support with the request_id. After a send, check GET /v1/messages before retrying, because the message may have gone out.

Whatsable or WhatsApp could not be reached for a moment. Nothing was sent.

Fix: Retry with backoff, with the same Idempotency-Key.

Whatsable stopped waiting for WhatsApp. The message may or may not have been sent.

Fix: Do not send the same message again until you confirm with the recipient. Our record showing failed is not proof it was not delivered.

Whatsable could not send this message, and WhatsApp returned no error code for it.

Fix: Check GET /v1/messages/{id} before sending again. If it keeps happening, contact Whatsable support with the message id.

WhatsApp refused the request because the access token or app permission is missing, expired, or insufficient.

Fix: Reconnect WhatsApp in Settings so Whatsable can refresh the token. Then retry.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp refused the request because the access token or app permission is missing, expired, or insufficient.

Fix: Reconnect WhatsApp in Settings so Whatsable can refresh the token. Then retry.

This WhatsApp app has used its hourly API budget, so WhatsApp is refusing further calls until the window resets.

Fix: Pause sends and retry later with backoff. Retrying immediately burns the same budget.

WhatsApp refused the request because the access token or app permission is missing, expired, or insufficient.

Fix: Reconnect WhatsApp in Settings so Whatsable can refresh the token. Then retry.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp rejected a field in this send (often the template, recipient, or message type).

Fix: Check the phone number format, template name and language, and required fields, then retry. This is usually the request, not a Whatsable outage.

The access token Whatsable holds for this WhatsApp number is expired or invalid, so WhatsApp refused the send.

Fix: Reconnect WhatsApp in Settings, then retry this step.

WhatsApp refused the request because the access token or app permission is missing, expired, or insufficient.

Fix: Reconnect WhatsApp in Settings so Whatsable can refresh the token. Then retry.

WhatsApp refused the request because the access token or app permission is missing, expired, or insufficient.

Fix: Reconnect WhatsApp in Settings so Whatsable can refresh the token. Then retry.

WhatsApp restricted this WhatsApp Business Account or number for a policy or quality reason.

Fix: Check quality and restrictions in WhatsApp Manager. Do not keep retrying until Meta lifts the restriction.

This WhatsApp Business Account has hit Meta's rate limit.

Fix: Reduce how many sends the scenario fires per minute and retry with backoff.

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number.

This phone number sent more messages per second than WhatsApp allows.

Fix: Queue messages and retry with backoff. This is a short spike, not a quality ban. Read the guide

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp restricted this WhatsApp Business Account or number for a policy or quality reason.

Fix: Check quality and restrictions in WhatsApp Manager. Do not keep retrying until Meta lifts the restriction.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp rejected a field in the request as invalid.

Fix: Check the template, phone number, and message type against Whatsable's send docs, then retry with a valid payload.

WhatsApp rejected a field in the request as invalid.

Fix: Check the template, phone number, and message type against Whatsable's send docs, then retry with a valid payload.

WhatsApp rejected a field in the request as invalid.

Fix: Check the template, phone number, and message type against Whatsable's send docs, then retry with a valid payload.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

The send targeted the same WhatsApp number it was sent from. WhatsApp does not deliver that.

Fix: Send to a different number than the connected WhatsApp Business number.

WhatsApp could not deliver to this number. Common causes: not a WhatsApp number, an old WhatsApp app, or the person has not accepted WhatsApp's latest terms.

Fix: Confirm the number is international digits without + or spaces. Ask the person to message you first from WhatsApp. Do not keep retrying this number. Read the guide

WhatsApp restricted this WhatsApp Business Account or number for a policy or quality reason.

Fix: Check quality and restrictions in WhatsApp Manager. Do not keep retrying until Meta lifts the restriction.

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number. Read the guide

WhatsApp restricted this WhatsApp Business Account or number for a policy or quality reason.

Fix: Check quality and restrictions in WhatsApp Manager. Do not keep retrying until Meta lifts the restriction.

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number.

More than 24 hours have passed since this person last messaged you, so WhatsApp blocked this free-form send.

Fix: Send an approved template instead of a session message. Do not retry this same free-form send. Read the guide

WhatsApp limited this number because too many previous messages were blocked or marked as spam. This is a quality restriction, not a short throughput spike.

Fix: Pause campaigns. Check quality in WhatsApp Manager. Only send to people who opted in. Retrying now will keep failing until Meta lifts the restriction.

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number. Read the guide

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number.

WhatsApp rejected a field in the request as invalid.

Fix: Check the template, phone number, and message type against Whatsable's send docs, then retry with a valid payload.

WhatsApp refused the media: type, size, or id is not accepted.

Fix: Send a supported file type under Meta's size limit. Do not retry the same bytes.

WhatsApp refused the media: type, size, or id is not accepted.

Fix: Send a supported file type under Meta's size limit. Do not retry the same bytes.

WhatsApp rejected a field in the request as invalid.

Fix: Check the template, phone number, and message type against Whatsable's send docs, then retry with a valid payload.

WhatsApp rate-limited this app, WABA, or phone number.

Fix: Slow the scenario down and retry with backoff. Do not hammer the same send.

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number.

WhatsApp rejected a field in the request as invalid.

Fix: Check the template, phone number, and message type against Whatsable's send docs, then retry with a valid payload.

WhatsApp restricted this WhatsApp Business Account or number for a policy or quality reason.

Fix: Check quality and restrictions in WhatsApp Manager. Do not keep retrying until Meta lifts the restriction.

The number of variables sent does not match the approved template.

Fix: Count every {{n}} in the body, header, and buttons, and send exactly that many values.

WhatsApp has no approved template with this name and language on the connected account.

Fix: Use the exact approved template name and language (en and en_US are different). Check Templates in Whatsable. Read the guide

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp accepted the request shape but could not deliver this message to the recipient.

Fix: Confirm the number is a WhatsApp user in international digits with no + or spaces. Do not keep retrying the same number.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp rate-limited this app, WABA, or phone number.

Fix: Slow the scenario down and retry with backoff. Do not hammer the same send.

WhatsApp refused the media: type, size, or id is not accepted.

Fix: Send a supported file type under Meta's size limit. Do not retry the same bytes.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp refused the template: name, language, status, or variables do not match an approved template.

Fix: Use an approved template, the exact name and language, and the same number of variables the template declares.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.

WhatsApp returned an error in a family we have not specialized yet.

Fix: Open Meta's error-code reference for this code. If it keeps happening, contact Whatsable support with the code.