When you make an API request, errors can occur due to authentication failures, invalid input, or processing issues. It's important to handle these errors properly by understanding their structure, status codes, and related messages. You can explore the details below.

Error Structure

If there’s an issue with your request, the API returns a 4XX or 5XX HTTP status code along with a structured error response. This response includes information about what went wrong.

{
    "status": "failed",
    "error": {
        "type": "REQUEST_NOT_VALID",
        "code": "10400",
        "message": "Request is not valid",
        "validation_errors": [
            {
                "field_name": "payment_method_id",
                "message": "must not be null"
            },
            {
                "field_name": "currency",
                "message": "must not be null"
            }
        ]
    }
}

The general structure of the error contains:

Parameter	Definition	Example
`status`	Indicates the outcome of the request.	`failed`
`error.type`	Describes the category of the error, such as validation, authentication, or processing issues.	`REQUEST_NOT_VALID`
`error.code`	A unique identifier for the error. Useful for debugging and custom error handling.	`10400`
`error.message`	A short message that explains the error.	`Invalid card number`
`error.validation_errors`	A list of specific validation errors, usually provided when there are issues with the input data.	`[{ "field_name": "card.encrypted_card_number", "message": "must not be null" }]`

General Error Codes

When a request fails, it returns an error code to help identify the issue and guide troubleshooting. Below is a list of common error codes, their meanings, and potential causes:

Code	Error Type	Definition	Possible cause
`10400`	`REQUEST_NOT_VALID`	The request was rejected due to invalid parameters or missing data.	Malformed request, missing parameters, or invalid JSON payload.
`10401`	`UNAUTHORIZATION`	The request requires authentication or has invalid credentials.	Missing API key, expired token, or incorrect credentials.
`10403`	`FORBIDDEN`	The client does not have permission to access the resource.	Insufficient privileges or access restrictions.
`10404`	`RESOURCE_NOT_FOUND`	The requested resource could not be found on the server.	Nonexistent endpoint, incorrect URL, or deleted resource.
`10409`	`RESOURCE_CONFLICT`	A conflict occurred due to duplicate or conflicting data.	Attempt to create an existing resource or version conflict.
`10422`	`UNPROCESSABLE`	The request was well-formed but contained invalid data.	Failed validation due to incorrect or incomplete fields.
`10500`	`INTERNAL_SERVER_ERROR`	An unexpected server error occurred while processing the request.	System failure or unhandled exceptions.

Collections or Inflow Payments Error Codes

Below is a list of error codes you may encounter when collecting payments. If you keep getting persistent errors, please contact our support team for assistance.

Code	Error Type	Definition	Possible Cause
`10400`	`REQUEST_NOT_VALID`	The request was rejected due to invalid parameters or missing data.	The JSON body is malformed, or required parameters are missing.
`10401`	`UNAUTHORIZED`	The request requires authentication or has invalid credentials.	Missing API credentials, expired token, or incorrect credentials.
`10403`	`FORBIDDEN`	The client does not have permission to access the resource.	Insufficient privileges or access restrictions.
`10404`	`RESOURCE_NOT_FOUND`	The requested resource could not be found on the server.	Nonexistent endpoint, incorrect URL, or deleted resource.
`10405`	`METHOD_NOT_ALLOWED`	Method not allowed	You used GET instead of POST (or vice versa).
`10409`	`RESOURCE_CONFLICT`	A conflict occurred due to duplicate or conflicting data.	Attempt to create an existing resource or version conflict.
`10422`	`UNPROCESSABLE`	The request was well-formed but contained invalid data.	Failed validation due to incorrect or incomplete fields.
`10500`	`INTERNAL_SERVER_ERROR`	An unexpected server error occurred while processing the request.	System failure or unhandled exceptions.
`701500`	`INVALID_PAGINATION_TYPE`	Invalid pagination type	The pagination parameters (page, limit) are formatted incorrectly.
`1100409`	`CHARGE_ALREADY_EXISTS`	Charge with reference already exists	You are reusing a transaction reference that has already been used.
`1101422`	`CUSTOMER_NOT_FOUND_FOR_CHARGE`	The Customer was not found for the charge.	The customer_id provided does not exist.
`1102422`	`PAYMENT_METHOD_NOT_FOUND_FOR_CHARGE`	The Payment method was not found for the charge.	The payment_method_id is invalid or does not belong to this customer.
`1104400`	`CARD_NOT_TOKENIZED`	The card is not tokenized.	You sent raw card data to an endpoint expecting a token/nonce.
`1105500`	`CHARGE_FAILED`	Could not complete charge.	General processing failure from the upstream provider.
`1106400`	`PAYMENT_METHOD_TYPE_MISSING`	Missing payment method type	The request body is missing the type field (e.g., card, bank_transfer).
`1107500`	`CHARGE_CREATION_FAILED`	Unable to create a charge	System error during the initialization of the charge. Kindly retry.
`1108400`	`CARD_RETOKENIZATION_REQUIRED`	Please retokenize the card.	The encryption or token used is invalid or expired.
`1110404`	`CHARGE_NOT_FOUND`	Charge not found	The charge ID provided does not exist.
1111400	CHARGE_FINALIZED	The Charge already has a final status	You cannot update or retry a transaction that is already successful or failed.
1112400	CHARGE_UPDATE_NOT_ALLOWED	The charge cannot be updated	The current state of the charge does not allow modification.
1113500	CHARGE_UPDATE_FAILED	Unable to update charge	System error during the update process.
1114400	ACCOUNT_ID_NOT_FOUND	No accountId found	Internal configuration error regarding the merchant account.
1118400	INVALID_CARD_NUMBER	Invalid card number	The card number length is incorrect or failed the Luhn check.
1119500	FAILED_TO_INITIATE_CHARGE	Failed to initiate charge	The payment provider rejected the initialization request.
1121400	INVALID_AUTHORIZATION	Failed to validate pre-existing charge	The PIN or OTP provided is incorrect.
1122400	FAILED_TO_VALIDATE_EXISTING_CHARGE	Failed to validate pre-existing charge	An error occurred while checking the status of a previous transaction.
1125400	CURRENCY_NOT_SUPPORTED	Currency not supported for payment type	Example: Trying to use UGX with a payment method that only supports NGN.
1126400	MOBILE_MONEY_COUNTRY_CODE_NOT_SUPPORTED	Country code not supported for Mobile Money	The country code provided is not valid for mobile money.
1127400	MOBILE_MONEY_NETWORK_NOT_SUPPORTED	Network not supported for Mobile Money.	The network (e.g., MTN, Airtel) is not supported in the selected region.
1128500	PAYMENT_CARD_TOKENIZATION_FAILED	Payment card details tokenization failed	Encryption failed. Check your encryption keys and logic.
1130400	AMOUNT_BELOW_MINIMUM	Amount below the minimum for the payment type	The transaction amount is too small to be processed.
1134422	CARD_EXPIRED	The Card has expired	The expiry date on the card is due.
1135422	CARD_EXPIRY_YEAR_OUT_OF_RANGE	Card expiry year out of range	The card expiry year provided is invalid.
1136422	CARD_EXPIRY_MONTH_OUT_OF_RANGE	Card expiry month out of range	The card expiry month provided is not between 01 and 12.
1137400	CLIENT_ENCRYPTION_ERROR	Unable to decrypt encrypted fields	The encryption logic is incorrect, or the wrong encryption key was used.
1138422	UNPROCESSABLE_F4B_RESPONSE	Unprocessable F4B response	An error was received from the banking partner system.
1139422	UNPROCESSABLE_CC_RESPONSE	Unprocessable CC response	An error was received from the card network/scheme.
1140400	CHARGE_NOT_SUCCESSFUL	The charge is not successful.	The transaction was declined by the bank or failed fraud checks.
1141400	REDIRECT_URL_INVALID	Redirect URL is invalid.	The redirect URL format is incorrect.
1142400	USSD_BANK_CODE_INVALID	Invalid bank code	The USSD bank code provided is incorrect
1150400	INVALID_CHARGE	Please use the /virtual-accounts resource	You are attempting to create a bank transfer using the wrong endpoint.
1100409	ORDER_ALREADY_EXISTS	Order with reference already exists	Duplicate order reference.
1101422	CUSTOMER_NOT_FOUND_FOR_ORDER	Customer not found for the order	The customer_id attached to the order is invalid.
1102422	PAYMENT_METHOD_NOT_FOUND_FOR_ORDER	Payment method not found for order	The payment_method_id attached to the order is invalid.
1110404	ORDER_NOT_FOUND	Order not found	The Order ID provided does not exist.
1111400	ORDER_FINALIZED	Order already has final status	You cannot modify an order that is already completed.
1112400	ORDER_UPDATE_NOT_ALLOWED	Order update is not allowed	The order state does not allow updates.
1143400	CAPTURE_AMOUNT_INVALID	Capture amount is greater than the order amount	You cannot capture more funds than were authorized.
1144400	PAYMENT_METHOD_MISMATCH	The payment method does not match the order	The payment method in the charge request differs from the Order.
1144400	CUSTOMER_MISMATCH	Customer does not match the order customer	The customer in the charge request differs from the Order.
1144400	CURRENCY_MISMATCH	Currency does not match the order currency	The currency in the charge request differs from the Order.
1145400	CAPTURE_VOID_NOT_ALLOWED	The order cannot be captured or voided	The order is not in a state (e.g., authorized) that allows capture/void.
1145400	PAYMENT_METHOD_INVALID	The payment method is invalid	The payment method provided is not valid for this order type.
1401404	REFUND_NOT_FOUND	Refund not found	The Refund ID provided does not exist.
1402400	REFUND_AMOUNT_INVALID	The refund amount cannot be more than the charge amount	You are attempting to refund more than the original transaction value.
1403400	REFUND_CREATION_FAILED	Refunds can't be initiated for pending transactions	You must wait for the transaction to be successful before refunding.
1404400	REFUND_ALREADY_COMPLETED	Charge already refunded	The transaction has already been fully refunded.
1500404	SETTLEMENT_NOT_FOUND	Settlement not found	The Settlement ID provided does not exist.
1600400	WEBHOOK_URL_INVALID	Webhook endpoint URL is invalid	The URL provided is not a valid HTTP/HTTPS URL.
1601404	WEBHOOK_ENDPOINT_NOT_FOUND	Webhook endpoint not found	No webhook configuration exists for this account.
1602422	UNPROCESSABLE_SVIX_RESPONSE	Unprocessable Svix response	Error communicating with the webhook provider (Svix).
1603500	INTERNAL_SERVER_ERROR_SVIX	Internal server error Svix response	System failure with the webhook provider.
1700404	CHARGEBACK_NOT_FOUND	Chargeback not found	The Chargeback ID provided does not exist.
1703400	CHARGEBACK_DECLINE_INVALID	Declined chargebacks must have a comment and proof	You rejected a chargeback without providing evidence.
1704400	CHARGEBACK_PROOF_INVALID	Invalid proof data	The file uploaded is corrupted or in an unsupported format.
1705500	CHARGEBACK_PROOF_UPLOAD_FAILED	Error uploading proof data	System error during file upload.
1706400	CHARGEBACK_DUE_DATE_INVALID	The chargeback due date is invalid	The deadline for responding to this chargeback has passed.
1707400	CHARGEBACK_AMOUNT_INVALID	The chargeback amount is invalid	The amount specified does not match the dispute amount.
1708400	CHARGEBACK_HAS_EXISTING_CHARGE	The charge already has an existing chargeback	A dispute is already in progress for this transaction.
1800404	CHECKOUT_SESSION_NOT_FOUND	Checkout section not found	The session ID provided does not exist or has expired.
1801409	CHECKOUT_SESSION_ALREADY_EXISTS	Checkout session with reference already exists	Duplicate session reference.
1900404	VIRTUAL_ACCOUNT_NOT_FOUND	Virtual account not found	The Virtual Account reference provided does not exist.
1900409	VIRTUAL_ACCOUNT_REFERENCE_ALREADY_EXISTS	Virtual account with that reference already exists	You are reusing a reference for a new virtual account.
1900500	VIRTUAL_ACCOUNT_UPDATE_FAILED	Virtual account update failed	System error during account update.
1900500	FAILED_TO_CREATE_VIRTUAL_ACCOUNT	Failed to create a virtual account	System error during account creation.
10503	VIRTUAL_ACCOUNT_CREATE_TIMEOUT	Request timeout	The provider took too long to generate the account. Retry.
19400	VIRTUAL_ACCOUNT_IS_ALREADY_INACTIVE	The virtual account is already inactive	You are trying to deactivate an account that is already closed.

Payout Error Codes

Transfers could fail due to different reasons. Read all possible error codes for payouts in the table below:

Code	Error Type	Definitions	Possible Cause
`0301`	`TRANSFER_AMOUNT_EXCEEDS_LIMIT`	The transfer amount exceeds the allowed limit.	The amount you are trying to transfer exceeds the maximum allowed limit for a single transfer.
`0302`	`TRANSFER_AMOUNT_BELOW_LIMIT`	The transfer amount is below the minimum amount required.	You are trying to transfer an amount that is below the minimum allowed amount.
`0303`	`MONTHLY_TRANSFER_LIMIT_EXCEEDED`	You have exceeded your monthly transfer limit.	You have reached the cumulative value of transfers allowed for your account in a single month.
`0304`	`DAILY_TRANSFER_LIMIT_EXCEEDED`	The daily transfer limit has been reached.	You have reached the cumulative value of transfers allowed on your account in a day.
`0305`	`TRANSFER_LIMIT_NOT_SET_FOR_CURRENCY`	The transfer limit has not been set for this currency.	There is no configured transfer limit for the specified currency. Kindly contact support.
`0306`	`PAYOUT_CREATION_FAILED`	An error occurred while creating the payout.	Temporary service timeout. Kindly retry again.
`0307`	`INSUFFICIENT_BALANCE`	You do not have sufficient funds.	Your wallet does not have sufficient funds to cover the transfer amount and the applicable fee.
`0308`	`SERVICE_UNAVAILABLE`	The service is temporarily unavailable.	Bank maintenance or network downtime
`0309`	`TRANSFER_FAILED`	We encountered an issue processing your transfer.	The destination account is closed or dormant, Network failure during processing.
`0310`	`PRICING_NOT_SET`	Pricing has not been set.	The transfer fee could not be determined. Kindly contact support.
`0311`	`CURRENCY_CONVERSION_NOT_SET`	Currency conversion has not been configured.	You are attempting a cross-currency transfer (e.g., USD Wallet to NGN Bank), but the exchange rate is not configured. Kindly contact support.
`0312`	`REJECTED_RECIPIENT_MERCHANT`	The recipient merchant is not eligible to receive transfers.	There are compliance or risk restrictions on the destination account.
`0313`	`INVALID_BANK_CODE`	The provided bank destination code is invalid.	You are passing an incorrect or outdated bank code.
`0314`	`UNABLE_TO_DETERMINE_COUNTRY`	The country for the provided bank code could not be determined.	The bank code format is incorrect. There is a mismatch between the bank code and the expected currency