Error Reference - Bila API Documentation

Error Codes

Status	Code	Cause	Fix
`400`	`INVALID_PHONE`	Wrong phone format	Use format `0977433571`
`400`	`INVALID_OPERATOR`	Unrecognised operator	Use `mtn`, `airtel`, or `zamtel`
`400`	`INVALID_AMOUNT`	Below minimum	Use amount ≥ `0.01`
`400`	`INSUFFICIENT_BALANCE`	Transfer exceeds balance	Check balance via `GET /bila/accounts`
`401`	`UNAUTHORIZED`	Key missing or invalid	Verify prefix is `sk_test_` and header is `x-api-key`
`409`	`DUPLICATE_REFERENCE`	Reference already used	Use a unique reference per transaction
`429`	`RATE_LIMITED`	Too many requests	Implement exponential backoff

To trigger a failed transaction, include the substring fail anywhere in your reference:

INV-2026-fail-001       ✓ fails
test-payment-will-fail  ✓ fails
INV-2026-001            ✓ succeeds

The sandbox does not expose specific PSP error codes. Outcomes are binary - successful or failed - with a message string stating the reason.