Error Codes

This guide lists all the error codes that Finix uses and what each of them means.

HTTP Error Status Codes

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.

You can test Transfers and Authorizations for specific responses and errors.

Requests to Finix's API return a response within less than a second. However, communications between card networks and processors can increase the time it takes to return a response.

Note: For card-present devices, response times can take longer depending on how quickly buyers complete a transaction on the payment terminal.

Because of this, requests to the Finix API have a maximum timeout of 5 minutes.

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.
`402`	DECLINED	The authorization was declined. Use the `failure_code` and `failure_message` for more details.
`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).
`422`	INVALID_FIELD	A provided field has an invalid value.
`429`	TOO_MANY_REQUESTS	A rate limit has been reached. Please wait, and try your request again after some time has passed.
`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`.