Error Codes Standardized error codes and how to handle them in your integration.
Chapa uses standardized HTTP status codes combined with machine-readable error codes and human-readable messages to help you quickly understand, debug, and handle errors correctly.
Every error response follows a predictable structure, making it easy to build robust and consistent error-handling logic.
All error responses follow this format:
{ "status" : "error" , "message" : "Invalid Currency" , "error" : { "code" : "INVALID_VALUE" , "details" : null } } Field Description statusAlways set to error messageA human-readable description of the error error.codeA machine-readable error identifier representing the error type error.detailsAdditional information about the error, if available; otherwise null
Status Meaning What To Do 400 Client Error Fix request payload or parameters 404 Not Found Check references or IDs 409 Conflict / Invalid State Fix flow logic (duplicate or invalid action) 500 Server Error Retry later
Error Type Error Code Message Description INVALID_FORMAT INVALID_FORMATInvalid payment method Payment method not recognized INVALID_VALUE INVALID_VALUEInvalid currency Unsupported currency INVALID_VALUE INVALID_VALUEAmount must be greater than minimum Amount below allowed limit INVALID_VALUE INVALID_VALUEAmount must be between {min} and {max} Amount out of range MISSING_REQUIRED_FIELD MISSING_REQUIRED_FIELDReference parameter is required Missing payment reference INVALID_STATE INVALID_STATETransaction reference has been used before Duplicate reference
Error Code Message Description NOT_FOUNDPayment not found Invalid or unknown reference NOT_FOUNDPayment request not found Initialization missing
Error Code Message Description PROCESSING_FAILEDFailed to initialize payment Temporary system issue PROCESSING_FAILEDFailed to fetch payments Retrieval error
Error Type Error Code Message Description INVALID_FORMAT INVALID_BANK_SLUGInvalid bank slug Bank identifier invalid INVALID_FORMAT INVALID_ACCOUNT_NUMBERInvalid account number Bank validation failed INVALID_VALUE INVALID_CURRENCYCurrency not supported by bank Currency mismatch OPERATION_NOT_SUPPORTED OPERATION_NOT_SUPPORTEDDirect charge not allowed Region or currency restriction
HTTP Error Code Message Description 404 NOT_FOUNDPayout not found Invalid payout reference 409 INVALID_STATEPayout already processed Duplicate or invalid operation
Error Code Message PROCESSING_FAILEDFailed to create payout PROCESSING_FAILEDFailed to fetch payouts PROCESSING_FAILEDFailed to fetch bank information
Error Code Message Description MISSING_REQUIRED_FIELDRefund ID is required Missing refund reference INVALID_STATEPayment is still pending Refund not allowed INVALID_STATEPayment already fully refunded Double refund blocked INVALID_STATEPayment failed or cancelled Invalid refund state
HTTP Error Code Message 404 NOT_FOUNDRefund not found 500 PROCESSING_FAILEDFailed to fetch refunds
Error Type Error Code Message Description INVALID_VALUE INVALID_SPLIT_TYPESplit type must be percentage or flat Invalid split type INVALID_VALUE INVALID_SPLIT_VALUESplit value invalid Out-of-range value RESOURCE_CONFLICT RESOURCE_CONFLICTSubaccount already exists Duplicate account NOT_FOUND NOT_FOUNDSubaccount not found Invalid reference
Error Code Message Description INVALID_FORMATInvalid phone number Phone format incorrect INVALID_VALUEEmail must be valid Email validation failed INVALID_STATECustomer is inactive Customer blocked INVALID_VALUEAPI key environment mismatch Test vs Live mismatch
Don't parse message
Always branch logic using error_code
Category Action 400 Fix request 404 Fix reference 409 Fix state flow 500 Retry later
Log:
error_codeTransaction reference
Timestamp
Never log:
API keys
PINs or OTPs
Full payloads with PII
Show users:
"Payment failed. Please try again."
Do not expose:
Internal error codes
Compliance or risk reasons
Point Description Consistent structure Error codes are consistent and predictable Use error_code Always branch logic using error_code Retry 500 errors 500 errors are usually retryable Fix 409 errors 409 errors usually indicate flow mistakes Build trust Proper error handling improves reliability and trust
