# 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](/additional-resources/developers/implementation-and-testing/testing-your-integration/).

### 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`](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors) 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](/additional-resources/developers/authentication-and-api-basics/rate-limits). |
| `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](#transfer-and-authorization-errors).


```json 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

| 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.


```json 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.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`. |