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.
What an error looks like
Every error from the API has the same shape:
{
"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 explains how. Opt-outs in English and 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 [email protected] 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. 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 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 page lists every code the API returns, with its status and whether a retry can help. The messaging docs cover delivery statuses and failure modes.