> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fexco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes and responses

> HTTP status codes and JSON error response fields returned by the Dynamic Currency Conversion (DCC) REST APIs.

The Dynamic Currency Conversion (DCC) REST APIs use standard HTTP status codes
to indicate the outcome of every request. In general, codes in the ranges below indicate the following:

* **2xx**: the request succeeded.
* **4xx**: the request failed due to a client error.
* **5xx**: the request failed due to an unexpected server error.

## HTTP status codes

The following table describes the status codes covered in this reference:

| Status code | Description |
| :- | :- |
| `200 OK` | Request succeeded. The Rate Service Classic API uses this for all successful responses, including when no DCC offer is available. |
| `201 Created` | Rate offer created successfully. |
| `202 Accepted` | Boarding batch accepted for asynchronous processing. |
| `400 Bad Request` | The request is invalid. The response body contains error details. |
| `401 Unauthorized` | Authentication failed. The bearer token is missing, expired, or invalid. |
| `403 Forbidden` | The authenticated client does not have permission to perform the requested operation. |
| `404 Not Found` | The requested resource does not exist. Verify the acquirer ID, merchant ID, and URL path. |
| `409 Conflict` | The Rate Service Connect API returns this when no rate offer is available. Check the response `details` array for the cause before deciding whether to retry. Only retry if the cause is transient (for example, a temporary service issue). Do not retry with the same request if the error is due to invalid input or an ineligible card. |
| `500 Internal Server Error` | An unexpected server error occurred. |
| `504 Gateway Timeout` | The Rate Service Connect API returns this when a socket timeout occurs. |

## Error response fields

Error responses use different JSON schemas across the DCC REST APIs.
Some include detail objects, depending on the API and the cause. The
following sections describe the fields returned by each:

### Boarding API

When a boarding request fails at the HTTP level, the Boarding API
returns a JSON body containing a list of errors:

```json theme={null}
{
  "status": "ERROR",
  "submittedAt": "2024-03-15T14:30:45.123Z",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "title": "Invalid Input",
      "message": "The provided location ID format is invalid."
    }
  ]
}
```

The table below describes each field:

| Field | Type | Description |
| :- | :- | :- |
| `status` | String | Response status. Always `ERROR` for error responses. |
| `submittedAt` | String (ISO 8601) | Timestamp when the request was submitted. |
| `errors` | Array | One or more error objects describing what failed. |
| `errors[].code` | String | Error code returned by the API. Treat the value as a string. |
| `errors[].title` | String | Short error title. Maximum 100 characters. |
| `errors[].message` | String | Detailed error message. Maximum 500 characters. |

> [!NOTE]
>
> Per-location boarding errors appear in the batch summary response,
> not in the HTTP 400 body. For the boarding workflow, see
> [Board merchants via REST API](https://docs.fexco.com/dcc/guides/merchant-boarding/board-api.md).

### Rate Service Classic API

When a Rate Service Classic request fails, the API returns a JSON body describing
the error:

```json theme={null}
{
  "timestamp": "2024-03-15T10:15:30Z",
  "url": "/dhsv2/acquirers/ABC/merchants/12345678/dccoffers",
  "error": "BAD_REQUEST",
  "status": 400,
  "message": "baseamount must be greater than zero."
}
```

The table below describes each field:

| Field | Type | Description |
| :- | :- | :- |
| `timestamp` | String (ISO 8601) | Timestamp when the error occurred. |
| `url` | String | The request path that caused the error. |
| `error` | String | Error type. One of: `BAD_REQUEST`, `NOT_FOUND`, `INTERNAL_SERVER_ERROR`. |
| `status` | Number | HTTP status code. |
| `message` | String | Error message describing the cause. |

### Rate Service Connect API

When a Rate Service Connect request fails, the API returns a JSON body.
Validation errors and no-offer conflicts include a `details` array with
one or more error objects. The examples below show the two most common
error patterns.

> [tab] Validation error (400)
>
> A `400` response indicates invalid input. The `details` array contains
> one or more error objects with a numeric error code identifying the
> problem. Correct the input before retrying.
>
> ```json theme={null}
> {
>   "timestamp": "2024-03-15T09:15:55.857Z",
>   "status": 400,
>   "error": "Bad Request",
>   "message": "Request validation failed.",
>   "path": "/dcc/offers",
>   "details": [
>     {
>       "code": "2",
>       "title": "Invalid Field Value",
>       "message": "Field 'orderDetails.amount' must be greater than zero."
>     }
>   ]
> }
> ```
>
> The following table lists the numeric error codes returned for eligibility
> and validation failures:
>
> | Error code | Scenario | Message |
> | :- | :- | :- |
> | 2 | Invalid field value or malformed request. | Varies by field. |
> | 4 | Unknown acquirer or merchant. | Unknown Acquirer or Merchant. |
> | 5 | BIN not recognized. | Unrecognised Card, DCC not available. |
> | 8 | Card type not supported for DCC. | Unsupported card type. |
> | 22 | Domestic card (base currency equals cardholder currency). | Domestic Card, DCC not available. |
> | 97 | Transaction amount is at or below the contactless TLL. | DCC not available as the transaction amount was less than or equal to the Contactless Transaction Lower Limit (TLL). |
> | 99 | Foreign card, but no rate is available for the currency. | Foreign Card, DCC not available. |

> [tab] No rate offer (409)
>
> A `409` response indicates that no rate offer is available. The `details`
> array includes the reason.
>
> ```json theme={null}
> {
>   "timestamp": "2024-03-15T09:15:55.857Z",
>   "status": 409,
>   "error": "Conflict",
>   "message": "No rate offer is available for the requested transaction",
>   "path": "/dcc/offers",
>   "details": [
>     {
>       "code": "22",
>       "title": "Domestic Card",
>       "message": "Domestic Card, DCC not available"
>     }
>   ]
> }
> ```

The table below describes each field:

| Field | Type | Description |
| :- | :- | :- |
| `timestamp` | String (ISO 8601) | Timestamp when the error occurred. |
| `status` | Integer | HTTP status code. |
| `error` | String | Short error category. For example, `Bad Request`. |
| `message` | String | Human-readable error message. |
| `path` | String | The request path that caused the error. |
| `details` | Array | Additional error detail objects. Included on validation `400` and no-offer `409` responses. |
| `details[].code` | String | Numeric error code identifying the error. |
| `details[].title` | String | Short title describing the error type. |
| `details[].message` | String | Detailed error message, including the rejected value where applicable. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.