Errors

Every error has the same JSON shape, a status code and a short code you can test for.

Error shape

{
  "error": {
    "code": "destination_not_allowed",
    "message": "This number is not a Malawi number. SMS YANU sends to Malawi (+265) numbers only. Nothing was charged.",
    "request_id": "req_8b1f0c2a",
    "details": {
      "allowed_country": "MW",
      "allowed_prefix": "+265",
      "hint": "Use a Malawi mobile number, for example +265888123456 or 0888123456."
    }
  }
}

Test for error.code in your code. The message text can change.
Give us the request_id when you contact support. It is also in the X-Request-Id response header.

Common errors

HTTP	Code	What it means	What to do
400	`bad_request`	Something in the request is wrong.	Read `message` and fix the request.
400	`invalid_destination`	The number is not a valid Malawi phone number.	Check the digits. See `details.hint`.
401	`unauthorized`	No key, or the key is wrong or deleted.	Check the `Authorization` header.
402	`insufficient_balance`	Your balance does not cover the message.	Top up, then send again.
403	`insufficient_scope`	The key may not do this action.	Use a key with the right scope.
403	`recipient_opted_out`	The number replied STOP to you.	Do not send to this number.
404	`not_found`	No such message, or it is not yours.	Check the id.
409	`duplicate_message`	Same text to the same number within 5 minutes, with duplicate protection on.	Wait, or turn the protection off.
422	`destination_not_allowed`	The number is not a Malawi (+265) number.	Use SMPP for other countries.
422	`validation_error`	A field is missing or has the wrong type. See `errors`.	Fix the field.
429	`rate_limited`	Too many requests.	Slow down and retry after a short wait.
500	`internal_error`	Something broke on our side.	Retry later. Contact support with the `request_id`.
503	`service_unavailable`	The service is busy or in maintenance.	Retry later.

Retrying

Retry 429, 500, 502 and 503 after a short wait, doubling the wait each time.
Always send an Idempotency-Key on sends, so a retry is never charged twice.
Do not retry 400, 401, 402, 403, 404 or 422 without changing something first.

To be confirmed

The error envelope, destination_not_allowed and invalid_destination follow the current code. The real message starts with the number you sent and details also repeats it as to. Other codes may still change.

Error shape

Common errors

Retrying

On this page