Error Codes

This page provides a comprehensive list of all error codes you may encounter when using the Chapa API, along with their definitions and possible solutions.

Authentication Errors

Error Message	Description	Solution
Unauthorized access	Missing or invalid authentication headers	Include proper authentication headers in your request
Token expired	Authentication token has expired (older than 5 minutes)	Generate a new authentication token
Invalid token	The provided authentication token is invalid	Verify your token format and regenerate if needed
Invalid authentication token	General authentication token validation failed	Check your authentication implementation

Authorization Errors

Error Message	Description	Solution
Unauthorized access	Request from unauthorized domain or IP address	Ensure requests are made from whitelisted domains (checkout.chapa.co or staging domain)

Validation Errors

Phone Number Validation

Error Message	Description	Solution
Phone number is required.	Phone number field is empty or missing	Provide a valid phone number in the request
Invalid Phone number, please use a proper phone number.	Phone number format is invalid or doesn’t meet length requirements	Use a valid Ethiopian phone number format (9-10 digits)
The phone number must be a valid Ethiopian phone number.	Phone number doesn’t match Ethiopian phone number format	Ensure phone number follows Ethiopian format: 7xxxxxxxxx or 9xxxxxxxxx
Phone number does not match the one used in the transaction.	Phone number doesn’t match the one used in the original transaction	Use the same phone number that was used in the original transaction

Payment Validation

Error Message	Description	Solution
The amount field is required.	Amount field is missing from the request	Include the amount parameter in your request
The amount field must be a number.	Amount is not a valid numeric value	Ensure amount is a valid number
The amount must not exceed maximum limit	Amount exceeds the maximum allowed limit (9,999,999.99)	Reduce the amount to within the allowed limit
Invalid/unrecognized account number.	Account number format is invalid or not recognized	Verify account number format for the specific bank
The email field must be a valid email address.	Email address format is invalid	Provide a valid email address format
The email field must be no more than 50 characters long.	Email address exceeds maximum length	Shorten email address to 50 characters or less
The first name field must be no more than 35 characters long.	First or last name exceeds maximum length	Shorten name to 35 characters or less
The CRF field is required.	Cross-site request forgery token is missing	Include the CSRF token in your request

Business & Account Errors

Error Message	Description	Solution
We’re sorry, but you have been blocked from making payments. Please contact support at 8911 for more information.	Customer account has been blocked from making payments	Contact Chapa support at 8911 to resolve account blocking
Payment is already completed for this transaction.	Attempt to process payment for an already completed transaction	Check transaction status before attempting payment
Retry failed. Please go back and re-initiate the payment again.	Retry not allowed for specific payment methods (telebirr, cbebirr)	Re-initiate the payment from the beginning
Insufficient balance	Account doesn’t have sufficient funds to complete the transaction	Ensure sufficient balance before attempting transaction

Bank-Specific Errors

Error Message	Description	Solution
Invalid account number	Account number is invalid	Verify account number format and existence
The OTP entered is incorrect	OTP verification failed	Re-enter the correct OTP code
The transaction is already completed	Transaction has already been processed	Check transaction status before proceeding
Please make sure your phone number is correct	User not found in Kacha system	Verify phone number is registered with Kacha
There was an issue with your payment, please try again!	Payment trace number error	Retry the payment with a new transaction reference
Your kacha account is inactive	Kacha account is not active	Contact Kacha support to activate your account
You don’t have enough balance to make this payment	Insufficient balance in Kacha account	Add funds to your Kacha account
Transaction was not successful with Ahadu Bank	General transaction failure with Ahadu Bank	Check transaction details and retry
OTP verification failed with Ahadu	OTP verification process failed	Re-enter the correct OTP code
Transaction was not successful with Oromia Bank	General transaction failure with Oromia Bank	Check transaction details and retry
Transaction was not successful with Zemen Bank	General transaction failure with Zemen Bank	Check transaction details and retry
Zemen account inquiry failed	Account inquiry process failed	Verify account details and retry
Something went wrong with Awash	General transaction failure with Awash Bank	Check transaction details and retry
Insufficient balance.	Insufficient balance for the transaction	Ensure sufficient balance before attempting transaction
This customer did not active Credit Pay service	Customer’s has insufficient balance and Credit Pay service is not activated in Telebirr	Ensure sufficient balance in Telebirr account or activate Credit Pay service

Service & Network Errors

Error Message	Description	Solution
Server took forever to respond	Bank or payment service server is not responding	Wait and retry the request
Failed to process your request	Payment service is temporarily unavailable	Wait and retry the request
E-birr took forever to respond	Payment service request timed out	Retry the request
Your payment information was not found, please try again.	Transaction reference not found in the system	Verify transaction reference and retry
Payment not completed. Please try again.	Payment process was not completed successfully	Retry the payment process

Transaction Status Errors

Error Message	Description	Solution
Transaction is nowhere to be found.	Transaction reference does not exist	Verify the transaction reference is correct
Transaction not found for OTP verification	Transaction not found for OTP verification	Verify transaction exists and is in correct status
Transaction status is not valid for OTP resend	Transaction status doesn’t allow OTP resend	Check transaction status before resending OTP
OTP can only be resent once per minute	OTP resend rate limit exceeded	Wait at least one minute before resending OTP

General Processing Errors

Error Message	Description	Solution
something went wrong	General processing error	Check request parameters and retry
Payment failed for unknown reason please try again.	Unknown payment failure	Retry the payment with same or different method
Wrong payment information	Invalid payment method or information	Verify payment method and details
An error occurred while processing your request. Please try again.	General processing error during request handling	Check request format and retry

Testing vs Live Mode

Remember to use the appropriate API keys and environments:

Test Mode: Use test API keys for development and testing
Live Mode: Use live API keys for production transactions

Never mix test and live keys - this will result in authentication errors.

Getting Help

If you encounter errors not listed here or need additional assistance:

Check the API Documentation for detailed response examples
Verify your implementation against the provided code samples
Contact Chapa support with your error details and transaction reference
Check the Status Page for any ongoing service issues
For urgent issues, contact support at 8911

Refund Roles & Permissions