Error Codes

Use these to handle failures gracefully and communicate accurate status to your users.

Error Code Reference Table

Code	Category	Direction	Description
`INCOMPLETE_AUTHENTICATION`	User Action	Payin	The user did not complete the payment prompt on their mobile device. The request timed out before confirmation.
`INSUFFICIENT_FUNDS_COLLECTION`	User Error	Payin	The customer's mobile money account does not have enough funds to cover the requested amount.
`INSUFFICIENT_FUNDS_PAYOUT`	Account Error	Payout	Your Centiwise wallet balance is too low to process this payout. Top up your account to continue.
`INVALID_ACCOUNT`	Validation	Payin / Payout	The provided phone number or account number is not registered with the specified provider.
`TRANSACTION_LIMIT_EXCEEDED`	Validation	Payin / Payout	The transaction amount exceeds the maximum allowed by the provider or the customer's account tier.
`DUPLICATE_TRANSACTION`	Validation	Payin / Payout	A transaction with the same reference already exists. Use a unique reference per request.
`INVALID_CURRENCY`	Validation	Payin / Payout	The currency code provided does not match the expected currency for the specified country.
`INVALID_PURPOSE`	Validation	Payin / Payout	The `purpose` value is not valid for the specified country or provider.
`PROVIDER_UNAVAILABLE`	Provider Error	Payin / Payout	The mobile money provider is temporarily unreachable. Retry after a short delay.
`TRANSACTION_FAILED`	Provider Error	Payin / Payout	The provider rejected or failed the transaction. Check the provider status or retry.
`TIMEOUT`	Provider Error	Payin / Payout	The transaction did not receive a response from the provider within the allowed time window.
`ACCOUNT_NAME_REQUIRED`	Validation	Payin / Payout	The `account_name` field is missing. This field is required for Rwanda (RWF) transactions.
`MISSING_REQUIRED_FIELD`	Validation	Payin / Payout	One or more required fields are absent from the request payload.
`INVALID_PHONE_FORMAT`	Validation	Payin / Payout	The phone number is not in the correct format for the specified country (e.g. Kenya requires `2547XXXXXXXX`).
`UNAUTHORIZED`	Auth	Payin / Payout	The API key is missing, invalid, or does not have permission to perform this action.
`RATE_LIMIT_EXCEEDED`	Auth	Payin / Payout	Too many requests have been made in a short period. Slow down and retry with backoff.

Error Detail Notes

INCOMPLETE_AUTHENTICATION

Triggered when the mobile money prompt (e.g. M-PESA STK push) is sent to the user but they do not enter their PIN within the timeout window.
The transaction is not charged. It is safe to retry or prompt the user to try again.
Common causes: user dismissed the prompt, poor network, or incorrect PIN entered too many times.

INSUFFICIENT_FUNDS_PAYOUT

Indicates your Centiwise account balance is too low to cover the payout amount plus any applicable fees.
Resolution: Top up your Centiwise wallet via your dashboard or contact your account manager.
This is distinct from INSUFFICIENT_FUNDS_COLLECTION, which relates to the end customer's wallet.

INSUFFICIENT_FUNDS_COLLECTION

Indicates the end customer's mobile money wallet does not have enough funds to complete the Payin.
The transaction is not charged. Inform the customer to top up their mobile wallet and retry.

PROVIDER_UNAVAILABLE / TIMEOUT

These are transient errors. Implement exponential backoff before retrying.
If the issue persists beyond a few minutes, check the provider's status or contact Centiwise support.

DUPLICATE_TRANSACTION

Each request must include a unique reference field.
If you need to retry a failed transaction, generate a new reference rather than reusing the old one.

Handling Errors

All error responses follow this structure:

{
  "status": "failed",
  "code": "INSUFFICIENT_FUNDS_COLLECTION",
  "message": "The customer's account does not have sufficient funds.",
  "reference": "your-unique-reference"
}

Recommended Handling by Category

Category	Recommended Action
User Action (e.g. `INCOMPLETE_AUTHENTICATION`)	Notify user and offer to retry
User Error (e.g. `INSUFFICIENT_FUNDS_COLLECTION`)	Notify user to top up and retry
Account Error (e.g. `INSUFFICIENT_FUNDS_PAYOUT`)	Top up Centiwise wallet; do not retry until resolved
Validation	Fix the request payload before retrying
Provider Error	Retry with exponential backoff; escalate if persistent
Auth	Check API key and permissions; do not retry automatically