error codes.md

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
`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 services.
`DECLINED`	The authorization was declined. See the `failure_code` and `failure_message` for more details.
`403`	`FORBIDDEN`	Your credentials do not 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 cannot accept the submitted request. Confirm 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.
`429`	`TOO_MANY_REQUESTS`	A rate limit has been reached. Please wait and try again after the rate limit has reset. See our rate limit guide here.
`500`	`SERVER_ERROR`	We 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.

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

Response Format

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

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.

{
    "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.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`.