Errors
Stable customer-facing codes and HTTP status mapping.
Error responses are JSON. Validation failures typically use 400. Auth failures use 401. Business rules such as wallet balance use dedicated codes.
Response shape
{
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient wallet balance. Need 25 TZS, have 0"
}HTTP status
| Status | Meaning |
|---|---|
400 | Invalid request, missing Sender ID, missing wallet, or bad input |
401 | Missing or invalid Bearer token / API key |
402 | Insufficient prepaid balance |
404 | Resource not found (e.g. message id) |
202 | SMS accepted and queued (success for send) |
Application codes
| Code | When |
|---|---|
MISSING_SENDER_ID | No senderId provided and no org/platform default available |
WALLET_MISSING | Organisation wallet could not be found |
INSUFFICIENT_BALANCE | Wallet balance lower than the send charge |
NOT_FOUND | Message or resource id does not exist |
MESSAGE_PROVIDER_ERROR | Customer-safe stand-in when delivery fails for provider/infrastructure reasons |
Provider noise is strippedFailed messages expose Netnaunse codes and messages only. Upstream provider payloads are never returned on customer APIs.