Error Codes

This guides explains the error codes Finix's API can return.

Error Code Overview

Finix uses standard HTTP status codes to indicate the outcome of API requests:

  • 2xx (Successful): Indicates the request was processed successfully.
  • 4xx / 5xx (Failed): Indicates the request failed due to client-side or server-side errors.

Testing Responses

You can simulate specific responses and errors for Transfers and Authorizations by following this guide.

Response Times

API responses are typically returned in under one second. However, factors such as communication delays with card networks and processors can increase response times.

Card-Present Transaction Latency

For card-present transactions, response times may be further delayed based on how quickly buyers complete actions on the payment terminal.

Timeout Limit

To accommodate potential delays, API requests have a maximum timeout 5 minutes.

List of Error Codes

These are the HTTP status codes Finix uses for errors.

HTTP Code error.code Description
400BAD_REQUESTYou provided a request that can not be successfully parsed. Verify you are providing valid JSON.
401UNKNOWNWe could not authenticate your request. You used an incorrect API Key.
402 UPSTREAM_PROCESSOR_ERRORErrors caused by 3rd-party services.
DECLINEDThe authorization was declined. See the failure_code and failure_message for more details.
403FORBIDDENYour credentials do not have the right permissions to submit the request.
404NOT_FOUNDThe specified resource could not be found.
405METHOD_NOT_ALLOWEDThe HTTP request method used to submit the request is not supported by the specified resource.
406NOT_ACCEPTABLEThe server cannot accept the submitted request. Confirm how the request was formatted and submitted.
409CONFLICTThe submitted request conflicts with the current state of the server.
422 UNPROCESSABLE_ENTITYThe 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_FIELDA provided field has an invalid value.
429TOO_MANY_REQUESTSA rate limit has been reached. Please wait and try again after the rate limit has reset. See our rate limit guide here.
500SERVER_ERRORWe had a problem with our server. Try again later.

Error Response Body

Requests with errors will 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.

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

Response Format

FieldDescription
error.codeA code to programmatically handle the error.
error.logrefA unique identifier for this specific API request and response.
error.messageA human-readable description of the error. Not to be coded/programmed to.

Transfer and Authorization Errors

Transfers and Authorizations return 400-level responses when declined. To provide additional context, Finix includes detailed information about the decline in the errors object.

Even when declines occur, Finix creates Transfer and Authorization resources in the background for tracking and record-keeping purposes. The error response includes the IDs of these resources.

Failed Authorization Example
{
    "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 Format

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