> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> Common sandbox error codes and how to fix them.

## 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                         |

***

## Simulating Failures

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

```text theme={null}
INV-2026-fail-001       ✓ fails
test-payment-will-fail  ✓ fails
INV-2026-001            ✓ succeeds
```

<Info>
  The sandbox does not expose specific PSP error codes. Outcomes are binary — `successful` or `failed` — with a message string stating the reason.
</Info>