Errors

When working with our API, you'll encounter five main kinds of errors: authorization errors, validation errors, server errors, Flutterwave errors, and provider errors. Each type of error comes with an appropriate HTTP status code.

All errors share the same basic response format: a status key set to "error", and a message describing the error. There may also be a data object containing more details, for example:

{
    "status": "error",
    "message": "merchant secret key required",
    "data": null
}

Authorization errors

You'll get authorization errors when you don't provide your secret key to authorize an API call, or when the key provided isn't correct. They come with a 401 Unauthorized status code:

{
    "status": "error",
    "message": "Authorization required",
    "data": null
}

Validation errors

Validation errors are returned when your request fails one or more validation rules. Examples include not passing required parameters. They come with a 400 Bad Request status code:

{
    "status": "error",
    "message": "Cardno is required",
    "data": null
}

Server errors

Server errors occur when something goes wrong on our end. In such a case, you should retry after a while, or reach out to our support. They come with a 500 Internal Server Error status code.

{
  "error_id": "ERRNO796977608T1620310828419",
  "message": "Application error. Please contact support",
  "code": "app_error"
}

Flutterwave errors

Flutterwave errors are typically returned when your request fails some limit / resource access / compliance checks.

They come with a 400 Bad Request status code. Here's a non-exhaustive list of some common error messages and their causes.

Error messageOccurs when...
"You can only charge Nigerian Accounts in Naira"you attempt to charge a Nigerian bank account with a currency other than NGN.
"USSD charges can only be done in Naira"you attempt a USSD charge with a currency other than NGN.
"Invalid Auth model. Preauth can only be used with NOAUTH/BVN"you attempt a PREAUTH charge passing an auth model other than NOAUTH / BVN.
"Transaction with ref EXAMPLE-REF either does not exist or is not a valid preauth transaction"you try to perform a capture on a transaction that doesn't exist or belong to your merchant or is not as a result of an initial PREAUTH charge call.
"Transaction has been flagged as fraudulent"This error occurs when a transaction's flagged by the fraud detection service used by Flutterwave.
"Token not found"This error occurs when an attempt is made to perform a tokenized charge with an invalid or non-existent token
"That token has expired"This error occurs when an already used token is passed as the token value when performing a tokenized charge.
"Transaction already complete"you try to validate an already completed transaction. (A transaction for which validation had previously been done)
"Transaction not found"you try to validate a transaction with a non-existent reference.
"Merchant limit is set at 3000 pending go live. Please contact support"your account has not been approved by the compliance team.
"Compliance Required. Please contact support"your account is under compliance review.
"Compliance status failure. Please contact support"your account's compliance submission has been rejected by the compliance team
"Merchant over the allowed" compliance value limityour account is under compliance review and you attempt a charge with an amount greater than the allowed in-review compliance limit.
"You have exceeded your daily limit"you attempt a charge with an amount greater than the daily transaction amount limit applicable to your merchant account
"Amount should be between xxxx and xxxxxxx"you attempt a charge with an amount greater than the maximum transaction amount and lesser than the minimum transaction
"Sorry, that country does not exist. Please check and try again"you pass a country code not currently supported by Flutterwave
"Currency: XXX does not exist"you pass a currency not currently supported by Flutterwave for charge calls.
"Merchant needs approval to make transactions."This error occurs mostly on Subdomain merchants that have not been approved by their parents for charge transactions
"Merchant is required to implement checksum. Please contact support"you are making a charge request without passing the integrity hash parameter
"Payment details mismatch. Please contact support"This error occurs when the hash passed for checksum enabled API requests do not match the server-generated hash.
"An error occurred while attempting to decrypt some parameters"This error occurs when request payload contains parameters encrypted wrongly
"Inactive public key passed"This error occurs when a public key that has been deactivated is passed during a charge call

Provider errors

Provider errors are returned from a payment provider such as a card issuer. They come with a 400 Bad Request status code. Here's a non-exhaustive explanation of some possible provider errors:

Error messageExplanation
UNSPECIFIED_FAILURETransaction could not be processed.
DECLINEDTransaction declined by issuer.
TIMED_OUTResponse timed out
EXPIRED_CARDTransaction declined due to expired card
INSUFFICIENT_FUNDSTransaction declined due to insufficient funds
ACQUIRER_SYSTEM_ERRORAcquirer system error occurred processing the transaction
SYSTEM_ERRORInternal system error occurred processing the transaction
NOT_SUPPORTEDTransaction type not supported
DECLINED_DO_NOT_CONTACTTransaction declined - do not contact issuer
ABORTEDTransaction aborted by payer
BLOCKEDTransaction blocked due to Risk or 3D Secure blocking rules
CANCELLEDTransaction canceled by payer
DEFERRED_TRANSACTION_RECEIVEDDeferred transaction received and awaiting processing
REFERREDTransaction declined - refer to issuer
AUTHENTICATION_FAILED3DS authentication failed
INVALID_CSCInvalid card security code
LOCK_FAILUREOrder locked - another transaction is in progress for this order
NOT_ENROLLED_3D_SECURECard holder is not enrolled in 3D Secure
EXCEEDED_RETRY_LIMITTransaction retry limit exceeded
DECLINED_AVSTransaction declined due to address verification
DECLINED_CSCTransaction declined due to card security code
DECLINED_AVS_CSCTransaction declined due to address verification and card security code
DECLINED_PAYMENT_PLANTransaction declined due to payment plan
UNKNOWNResponse unknown
CARD_NOT_ENROLLEDThe card is not enrolled for 3DS authentication
AUTHENTICATION_NOT_AVAILABLEAuthentication is not currently available
AUTHENTICATION_ATTEMPTEDAuthentication was attempted but the card issuer did not perform the authentication
CARD_DOES_NOT_SUPPORT_3DSThe card does not support 3DS authentication
Loading...