Errors

Learn how to handle errors


Finix uses an HTTP status code to communicate the success or failure of an API Call:

  • A 2xx HTTP status code gets used for all successful API calls.
  • A 4xx or 5xx HTTP status code gets used for errors.

For transfer and authorizations, you can test for specific responses and errors.

4xx and 5xx Status Codes

These are the HTTP status codes Finix uses for errors.

HTTP Code error.code Description
400 BAD_REQUEST You provided a request that can not be successfully parsed. Verify you are providing valid JSON.
401 UNKNOWN We could not authenticate your request. You used an incorrect API Key.
402 UPSTREAM_PROCESSOR_ERROR Errors caused by 3rd party service.
403 FORBIDDEN Your credentials don't have the right permissions to submit the request.
404 NOT_FOUND The specified resource could not be found.
405 METHOD_NOT_ALLOWED The HTTP request method used to submit the request is not supported by the specified resource.
406 NOT_ACCEPTABLE The server can't accept the submitted request. Double-check how the request was formatted and submitted.
409 CONFLICT The submitted request conflicts with the current state of the server.
422 UNPROCESSABLE_ENTITY The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved).
INVALID_FIELD A provided field has an invalid value.
500 SERVER_ERROR We had a problem with our server. Try again later.

Error Response Body

All errors return an array of errors. Below is an example of one error that can be returned from any resource (except Transfers and Authorizations).

For Transfer and Authorization errors see Transfer and Authorization Errors.

Copy
Copied
{
  "total" : 1,
  "_embedded" : {
    "errors" : [ {
      "logref" : "d4ee0b6cdb67686f0c1ec0780e5b4296",
      "message" : "Malformed request. ",
      "code" : "BAD_REQUEST",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/merchants"
        }
      }
    } ]
  }
}

Response

Field Description
error.code A code to programmatically handle the error.
error.logref A unique identifier for this specific API request and response.
error.message A human-readable description of the error. Not to be coded/programmed to.

Transfer and Authorization Errors

Some declines, Transfers, and Authorizations return a 4xx response when declined. We include additional information in the errors object about the decline, and the ID of the declined Transfer or Authorization in the response.

We still create a Transfer or Authorization resource in the background, so you have a clear list of approved and declined payments.

Copy
Copied
{
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "logref": "3fe8e6ab1e8cf44f",
                "message": "Authorization AUst6ZdywPwe4fbYWrH1zTNJ was declined Cause: Authorization AUst6ZdywPwe4fbYWrH1zTNJ could not be submitted. Cause: Generic Decline",
                "code": "DECLINED",
                "authorization": "AUst6ZdywPwe4fbYWrH1zTNJ"
                "failure_code": "GENERIC_DECLINE",
                "failure_message": "The card was declined for an unknown reason. The cardholder needs to contact their issuer for more information.",
                "_links": {
                    "self": {
                        "href": "https://finix.sandbox-payments-api.com/authorizations"
                    },
                    "authorization": {
                        "href": "https://finix.sandbox-payments-api.com/authorizations/AUst6ZdywPwe4fbYWrH1zTNJ"
                    }
                }
            }
        ]
    }
}

Response

Field Description
error.authorization The Authorization ID of the declined authorization. This is only populated for authorization errors that result in a created Authorization.
error.code A code to programmatically handle the error. For Authorizations and Transfers this field is now deprecated in favor of failure_code.
error.failure_code The code of the failure so the decline can be handled programmatically.
error.failure_message A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.
error.logref A unique identifier for this specific API request and response.
error.message A human-readable description of the error. For Authorizations and Transfers this field is now deprecated in favor of failure_message.
error.transfer The Transfer ID of the declined authorization. This is only populated for transfer errors that result in a created Transfer.

Failure Codes

When a transaction gets declined, Finix lets you know by returning a failure_code and failure_message. The failure_message in the response details the steps you need to take to complete the payment.

Here's a list that includes some of the most common failure_codes and their failure_messages.

attention

These failure codes are only for Finix Flex and Finix Core.

Failure Code Failure Message
ADDRESS_VERIFICATION_FAILED_RISK_RULES The Risk Rules associated to the Merchant declined the transaction. The cardholder needs to create a card with the correct address.
AUTHORIZATION_EXPIRED_OR_ALREADY_CAPTURED The authorization is either expired or has already been captured. The cardholder needs to create a new authorization.
CALL_ISSUER The card was declined for an unknown reason. The cardholder needs to contact their card issuer for more information.
CARD_ACCOUNT_CLOSED The card account has been closed. The cardholder should use an active card.
CARD_NETWORK_ERROR There is a problem with the card network. Contact the network for more information.
CARD_NOT_SUPPORTED The card does not support this type of purchase. The cardholder needs to contact their issuing bank to make sure their card can be used to make this type of purchase.
CARDHOLDER_PREVENTED_RECURRING_TRANSACTION Cardholder requested that recurring or installment transaction to be stopped.
COMMUNICATION_ERROR There was a network communication error with the host. Check your network connection and retry the transaction.
CVV_FAILED_RISK_RULES The Risk Rules associated with the Merchant declined the transaction. The cardholder needs to create a card with the correct CVV.
DO_NOT_HONOR The card was declined for an unknown reason. The cardholder needs to contact their issuing bank for more information.
DUPLICATE_TRANSACTION A transaction with the same amount and card was approved recently and marked as a duplicate. If this duplicate transaction was intentional, set check_for_duplicate_transactions to false.
EXCEEDS_APPROVAL_LIMIT The transaction was declined because it exceeded the daily approval limit for the card. The cardholder needs to use a different card.
EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT The card has exceeded its withdrawal frequency limit. The cardholder needs to use a different card.
EXPIRED_CARD The card has expired. The cardholder needs to use another card that's not expired.
FRAUD_DETECTED The card was declined for fraud by the processor. The customer should contact their card issuer for more information.
GENERIC_DECLINE The card was declined for an unknown reason. The cardholder needs to contact their issuer for more information.
INACTIVE_CARD The card is inactive. The cardholder needs to activate the card or use an active card.
INSUFFICIENT_FUNDS The card has insufficient funds for the transaction. The cardholder needs to use another card.
INVALID_ACCOUNT_NUMBER The card number is not valid. The cardholder needs to contact their issuing bank for more information or use another card.
INVALID_AMOUNT The amount exceeds the amount that is allowed on the card. The cardholder needs to check with their issuing bank to see if they can make purchases of that amount.
INVALID_CVV The CVV number is invalid. The cardholder needs to attempt the transaction again using the correct CVV.
INVALID_ISSUER The card number is not associated to a valid card issuing bank. The cardholder needs to contact their issuing bank.
INVALID_ROUTING_NUMBER The bank routing number provided is invalid. The bank account holder needs to provide a valid routing number.
INVALID_TRANSACTION The transaction is not permitted by the issuing bank. The cardholder needs to contact their issuing bank for more information.
LOST_OR_STOLEN_CARD The transaction was declined because the card is reported lost or stolen.

Don't return the LOST_OR_STOLEN_CARD failure_code and failure_message to cardholders. Instead, return a generic decline.
MAX_TRANSACTION_AMOUNT_EXCEEDED The transaction was declined because it exceeded the max transaction amount that's associated with the Merchant. The cardholder needs to reprovision the Merchant with a higher max transaction amount or create a transaction with a lower amount.
PICK_UP_CARD The card has been reported as lost or stolen by the cardholder. The cardholder needs to contact their issuing bank.
RESTRICTED_CARD The card has a restriction preventing approval for this transaction. Please contact the issuing bank for a specific reason.
RESUBMIT_TRANSACTION The transaction couldn’t be processed by the issuer for an unknown reason. The cardholder needs to attempt the transaction again. If the transaction is declined again, the cardholder should contact their issuing bank.
TRANSACTION_NOT_PERMITTED The transaction was declined because the card type is not permitted. The cardholder needs to use a different type of card.

Push to Card Errors

Below are the different error values that the messages attribute can return for Push to Card.

Error Code Messages
REFER_TO_CARD_ISSUER Please contact card issuer for more information.
INVALID_MERCHANT Merchant not permitted for this transaction type
PICK_UP_CARD_NO_FRAUD Please contact card issuer for more information.
DO_NOT_HONOR Please contact card issuer for more information.
ERROR Please attempt transaction again but if it still cannot be processed try again at a later time
PICK_UP_CARD_FRAUD_ACCOUNT Please contact card issuer for more information.
INVALID_TRANSACTION Issuing bank does not support this transaction type on this card. Please contact card issuer for more information.
INVALID_AMOUNT_OR_CURRENCY Transaction violates network amount limit.
INVALID_ACCOUNT_NUMBER The account number does not exist. Please make sure the account number is correct or contact your issuer.
NO_SUCH_ISSUER The issuer can not be found. Please check card number to ensure it is valid.
RE_ENTER_TRANSACTION Please attempt transaction again and contact card issuer if it still cannot be processed.
NO_ACTION_TAKEN Please contact card issuer for more information.
UNABLE_TO_LOCATE_RECORD The account number does not exist. Please make sure the account number is correct or contact your issuer.
FILE_TEMPORARILY_NOT_AVAILABLE Please contact card issuer for more information.
NO_CREDIT_ACCOUNT Issuer has declined the transaction because the card is not a credit account. Please try another card.
LOST_CARD_PICK_UP_FRAUD_ACCOUNT Please contact card issuer for more information.
STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT Please contact card issuer for more information.
NOT_SUFFICIENT_FUNDS Card issuer has declined the transaction as it does not have sufficient funds.
NO_CHECKING_ACCOUNT The card is not tied to a checking account and thus cannot be processed. Please try another card.
NO_SAVINGS_ACCOUNT The card is not tied to a savings account and thus cannot be processed. Please try another card.
EXPIRED_CARD The expiration date is expired or missing. Please correct and try again.
INCORRECT_PIN The PIN is invalid or missing. Please try again with the correct PIN.
TRANSACTION_NOT_PERMITTED Transaction not permitted to cardholder. Please contact card issuer for more information.
SUSPECTED_FRAUD Please contact card issuer for more information.
EXCEEDS_APPROVAL_AMOUNT_LIMIT Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card.
RESTRICTED_CARD Card not supported in this region or country. Please contact card issuer for more information.
TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT This transaction does not fulfill compliance requirements and cannot be processed.
EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT Please attempt with another card or contact card issuer for more information.
ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method.
CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN The supplied PIN is invalid.
NEGATIVE_RESULTS Invalid security code.
CANNOT_VERIFY_PIN The PIN is invalid or missing. Please try again with the correct PIN.
ISSUER_INOPERATIVE Please attempt transaction again and contact card issuer if it still cannot be processed.
FINANCIAL_INSTITUTION_NOT_FOUND The issuer can not be found. Please check card number to ensure it is valid.
TRANSACTION_NOT_COMPLETED_LAW_VIOLATION The transaction cannot be completed because it violates a law.
SURCHARGE_AMOUNT_NOT_SUPPORTED The supplied surcharge amount is not supported by the issuer.
TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT Transaction violates amount limit.
CARD_AUTHENTICATION_FAILED Please contact card issuer for more information.
STOP_PAYMENT_ORDER Please contact card issuer for more information.