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

# API errors

> HTTP status codes and errorCode values for rejected requests.

When Tanda rejects a request, it returns a standard HTTP status and a JSON body:

```json theme={null}
{
  "success": false,
  "message": "Duplicate external reference",
  "errorCode": "DUPLICATE_EXTERNAL_REFERENCE"
}
```

> [!TIP]
>
> Branch your code on `errorCode`. `message` is for people and its wording can change.

> [!NOTE]
>
> These are errors on the **request**. A request can succeed and the payment still fail later, for example if the customer cancels the prompt. Those failures arrive by webhook; see [Transaction errors](https://api.tandapay.io/guides/errors/transaction-errors.md).

## Common errors

| HTTP | `errorCode` | Meaning | What to do | Retry? |
| :-: | :- | :- | :- | :-: |
| 401 | – | Token missing, invalid or expired. | Mint a new token and retry once. | Once |
| 403 | `USER_NOT_ONBOARDED` | Your account isn't fully approved yet. | Finish onboarding in the dashboard or contact support. | No |
| 409 | `DUPLICATE_EXTERNAL_REFERENCE` | That `externalReference` was already used. | Look up the existing transaction with [Get transaction](https://api.tandapay.io/api-reference/endpoint/get-transaction.md). | No |
| 422 | `INSUFFICIENT_FUNDS` | Your wallet balance is too low. | Top up, then retry. | After top-up |
| 500 | `INTERNAL_SERVER_ERROR` | Something went wrong on our side. | Retry with backoff; contact support if it continues. | Yes |

## Collections

| HTTP | `errorCode` | Meaning | What to do |
| :-: | :- | :- | :- |
| 403 | `METHOD_NOT_ENABLED` | The method isn't enabled on your account. | Ask support to enable it. |
| 403 | `CURRENCY_NOT_ENABLED` | KES collections aren't enabled on your account. | Ask support to enable them. |
| 404 | `PROVIDER_NOT_FOUND` | No network matches the number, method or amount. | Check the phone number and amount. |
| 422 | `UNSUPPORTED_CURRENCY` | The currency isn't supported. | Send `KES`. |

## Payouts

| HTTP | `errorCode` | Meaning | What to do |
| :-: | :- | :- | :- |
| 403 | `CURRENCY_NOT_ENABLED` | Payouts aren't enabled on your account. | Ask support to enable them. |
| 404 | `PAYOUT_PROVIDER_NOT_FOUND` | No provider for that destination. | Check `destination` and `payoutMethod`. |
| 422 | `MOMO_CODE_REQUIRED` | A mobile money payout is missing `payoutMethod.code`. | Send `mpesa` or `airtel`. |
| 400 | `VALIDATION_ERROR` | A field is missing or invalid. | Fix the field named in `message`. |

## Handling errors well

* **Retry only what's retryable.** `5xx` errors are worth retrying with exponential backoff. `4xx` errors need you to change the request or your account first.
* **Retry with the same `externalReference`.** If a request times out and you resend it, a `409` means Tanda already has that transaction. Look it up with [Get transaction](https://api.tandapay.io/api-reference/endpoint/get-transaction.md) rather than sending it again with a new reference.
* **Validate first.** Resolve payout recipients with [Account resolver](https://api.tandapay.io/api-reference/endpoint/account-resolver.md) and check phone formats before sending.
* **Check service health** with [Service status](https://api.tandapay.io/api-reference/endpoint/service-status.md) before retrying many failures at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.