Errors

Errors are returned as JSON with a detail field (standard FastAPI shape):


{ "detail": "Insufficient balance. Need KES 25.00, have KES 10.00." }

The one exception is the generic 500 handler, which returns:


{ "error": "Internal server error", "status_code": 500 }

Status codes

Code	Meaning
`400`	Bad request — validation failure, malformed input
`401`	Missing/invalid credentials, or an expired/invalid token
`402`	Insufficient wallet balance for the requested send
`403`	Authenticated, but not permitted (e.g. non-admin calling an admin route, suspended account)
`404`	Resource not found, or not owned by the authenticated user
`409`	Conflict — duplicate email, phone number, or Sender ID request
`429`	Too many incorrect verification-code attempts
`500`	Unexpected server error

A 401 on a suspended account includes an X-Error-Code: account_suspended response header so clients can distinguish “suspended” from “session expired” and show the right message.