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.

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.

Sources

Copy linkMarkdown

/ More guides

Build the next thing, from Rwanda.

Get started