# SMS API errors and what your code should do about each

> The errors a BWEZE SMS send can return, with the HTTP status, the meaning and what your code should do, and what to do when a message ends in failed.

Source: https://sms.bweze.com/guides/sms-errors/ · Updated 2026-11-19

A send to `POST /v1/messages` answers with the message, or with an error. This guide lists the errors a send can return and what your code should do about each. When and how to retry is in [Retrying an SMS send without sending it twice](/guides/retry-sms-safely/).

## What an error looks like

Every error from the API has the same shape:

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "...",
    "docs": "https://docs.bweze.com/errors/insufficient_balance"
  }
}
```

Branch on `code`, never on `message`. Messages are written for people and may change. `docs` links to the code's row in the reference. The Node SDK, `@bweze/messaging`, throws a typed `BwezeError` with the same `code` and `docs` URL.

## The message and the recipient

| Code                    | HTTP | Meaning                                                 | What to do                                                                                                         |
| ----------------------- | ---- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `invalid_recipient`     | 400  | `to` is not a phone number BWEZE can send to            | Ask the user to correct the number. Send it in international format; a number starting with `0` is read as Rwandan |
| `empty_body`            | 400  | The message would be empty                              | Check that `body`, or `template` with its `data`, gives some text                                                  |
| `message_too_long`      | 400  | More than 10 segments                                   | Shorten it, and preview it before you send                                                                         |
| `recipient_opted_out`   | 409  | The recipient texted STOP                               | Treat it as final. Record it, and offer the user another way, such as email                                        |
| `messaging_rejected`    | 4xx  | The SMS gateway refused the message; `message` says why | Log `message` and fix the cause. Never send it again as it is                                                      |
| `messaging_unavailable` | 503  | The SMS gateway could not be reached                    | Retry later with the same idempotency key                                                                          |

A message needs more segments than you expect when one character pushes it out of GSM-7; [GSM-7 or Unicode](/guides/gsm-7-vs-unicode/) explains how. [Opt-outs in English and Kinyarwanda](/resources/opt-outs-in-kinyarwanda/) covers the words recipients reply with and what to do after an opt-out.

## Money and idempotency keys

| Code                             | HTTP | Meaning                                                               | What to do                                                                  |
| -------------------------------- | ---- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `insufficient_balance`           | 402  | The wallet's available balance cannot cover this. Nothing was charged | Tell a workspace owner: only owners can top up. Send again after the top-up |
| `idempotency_key_reuse_mismatch` | 409  | This idempotency key was already used with different content          | Fix how you make keys. A new message needs a new key                        |

API tokens can never top up. An owner can turn on **auto reload** under **Billing**, which sends a mobile money payment request when what the wallet can pay falls below a threshold; the payer approves it with their PIN.

## The request and the token

| Code                                                  | HTTP | Meaning                                                                        | What to do                                                                                                     |
| ----------------------------------------------------- | ---- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `invalid_request`, `invalid`                          | 400  | The body is not valid JSON, or a field is missing or wrong; `message` names it | Fix the body                                                                                                   |
| `missing_api_key`                                     | 401  | No `Authorization: Bearer` header                                              | Send the token                                                                                                 |
| `invalid_api_key`                                     | 401  | The token is unknown, revoked or mistyped                                      | Use a live token                                                                                               |
| `token_expired`                                       | 401  | After the token's expiry                                                       | Roll or replace the token                                                                                      |
| `rate_limited`                                        | 401  | More than 300 requests in a minute on this token                               | Wait until the minute is up                                                                                    |
| `secret_key_required`, `publishable_key_write_denied` | 403  | A publishable `bw_pk_` token was used where a secret `bw_sk_` token is needed  | Send from your server, with a secret token                                                                     |
| `token_permission_denied`                             | 403  | The token was not granted this action                                          | Grant `message:send` to send and `message:read` to preview, or use a token made from the **Send SMS** template |
| `internal_error`                                      | 500  | Something broke on BWEZE's side                                                | Retry later with the same key. If it keeps happening, write to hello@bweze.com with the time and the request   |

The other token errors, such as `token_ip_denied` and `key_role_denied`, are in the [API tokens docs](https://docs.bweze.com/docs/api-tokens#errors). None of them succeeds on a retry: change the token, or use another one.

## A message that ends in failed

An error comes back in the response to the send. A message can also fail later. A send that answered `200` with `status: "sent"`, or `202` with `status: "queued"`, can still end in `failed`, `rejected` or `expired`. Each of the three means it will not arrive. `unknown` means the carrier gave no final answer. Delivery receipts move a message forward, never back.

The `rejected` status and the `messaging_rejected` error are different moments. The error is the SMS gateway refusing the send, in the response to your request. The status comes later, from a delivery receipt.

There is no API endpoint or webhook for delivery status yet. You see each message's status in BWEZE Platform, and your code learns nothing after the send response. Until that changes, design for a message that never arrives:

- **Let the user ask again.** A sign-in screen should offer a new code after a short wait. The [quickstart](https://docs.bweze.com/docs/quickstart) makes resends wait 60 seconds.
- **Send a new message with a new key.** A retry with the old key returns the first result and sends nothing.
- **Check BWEZE Platform** when one user reports a missing message, to see where it stopped.

## The full reference

The [error codes](https://docs.bweze.com/docs/errors#sms) page lists every code the API returns, with its status and whether a retry can help. The [messaging docs](https://docs.bweze.com/docs/messaging) cover delivery statuses and failure modes.

## Sources

- [BWEZE docs: Error codes](https://docs.bweze.com/docs/errors)
- [BWEZE docs: Messaging](https://docs.bweze.com/docs/messaging)
- [BWEZE docs: Building with agents (error contract)](https://docs.bweze.com/docs/agents)
- [BWEZE docs: API tokens](https://docs.bweze.com/docs/api-tokens)
- [BWEZE docs: Billing](https://docs.bweze.com/docs/billing)
- [BWEZE docs: Quickstart](https://docs.bweze.com/docs/quickstart)
