Error Codes Comprehensive list of all error codes you may encounter when using the Chapa API, along with their definitions and possible solutions
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.
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
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)
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
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
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
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
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
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
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
Remember to use the appropriate API keys and environments:
Test Mode: Use test API keys for development and testingLive Mode: Use live API keys for production transactions
Never mix test and live keys - this will result in authentication errors.
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
