Error codes and responses - Fexco Developer Portal

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:

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

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.

Rate Service Classic API

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

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

Validation error (400)
No rate offer (409)

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.

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

A 409 response indicates that no rate offer is available. The details array includes the reason.

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