API errors

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

{
  "success": false,
  "message": "Duplicate external reference",
  "errorCode": "DUPLICATE_EXTERNAL_REFERENCE"
}

Branch your code on errorCode. message is for people and its wording can change.

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.

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.	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 rather than sending it again with a new reference.
Validate first. Resolve payout recipients with Account resolver and check phone formats before sending.
Check service health with Service status before retrying many failures at once.

Get started

Accept payments

Send payouts

Webhooks

Go live

Common errors

Collections

Payouts

Handling errors well

​Common errors

​Collections

​Payouts

​Handling errors well

Common errors

Collections

Payouts

Handling errors well