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

# Troubleshoot rate service errors

> Diagnose and resolve common Dynamic Currency Conversion (DCC) rate request failures.

Use this page when a rate request fails, returns unexpected
results, or DCC is not offered when you expect it to be. Find
your problem below and follow the steps to resolve it.

## Before you troubleshoot

Before you troubleshoot a specific error, run through these checks:

* Confirm you are using the correct environment (production or
  cert). See
  [Environments and URLs](https://docs.fexco.com/dcc/api-reference/environments.md).
* Verify your acquirer ID and merchant ID match the values
  provided by Fexco.
* Check that the request URL or message does not contain typos,
  double slashes, or missing path segments.
* For Rate Service Classic, verify that DHS is active by sending a
  heartbeat request:

  ```bash theme={null}
  curl "https://YOUR_DHS_HOST/dhsv2/heartbeat"
  ```

  A successful response returns `{"ok": true}`. If the heartbeat
  fails, DHS may be unavailable. Contact your Fexco project
  manager.

## DCC offer not returned for a card

The following results are not errors. They mean DHS processed the
request but the card is not eligible for DCC. In each case,
process the transaction in the merchant's base currency.

> [accordion] Empty response from Rate Service Classic
>
> The Rate Service Classic API returns HTTP `200` with an empty JSON body
> (`{}`).
>
> ### Why this happens
>
> An empty response means DHS processed the request but the card
> is not eligible for DCC. Common reasons include:
>
> * The BIN or card number is not recognized as a foreign card.
> * The card is ineligible for DCC under card scheme rules.
> * The card currency is not supported by the merchant's DCC
>   configuration.
> * The card scheme is not allowed for the merchant ID.
> * No rates are available for the specified merchant ID or
>   currency.
>
> ### How to fix
>
> No corrective action is needed. Process the transaction in the
> merchant's base currency. See
> [Handle domestic and unsupported cards](https://docs.fexco.com/dcc/guides/rate-service/domestic-unsupported.md)
> for guidance on what to display to the cardholder.

> [accordion] Domestic card, DCC not available (code 22)
>
> The ISO API returns response code `22`, or Rate Service Connect
> returns error code `22` with the message "Domestic Card, DCC
> not available."
>
> ### Why this happens
>
> The merchant's base currency matches the cardholder's card
> currency. DCC only applies when the card currency is different
> from the merchant's settlement currency.
>
> ### How to fix
>
> No corrective action is needed. Process the transaction in the
> merchant's base currency without offering DCC.

> [accordion] Unrecognized card (code 5)
>
> The ISO API returns response code `5`, or Rate Service Connect
> returns error code `5`.
>
> ### Why this happens
>
> This code is returned in either of the following cases:
>
> * DHS could not determine the currency of the card from the BIN
>   provided. The card may be from an issuer whose BIN range is
>   not in the DHS database.
> * The card is ineligible for DCC under card scheme rules. This
>   includes cards or accounts identified in the Mastercard
>   Parameter Extract (MPE) as ineligible for point of interaction
>   (POI) currency conversion, Visa account ranges enabled with the
>   Visa Multi-Currency Solution, and travel prepaid cards such as
>   Visa TravelMoney.
>
> ### How to fix
>
> 1. Confirm that the BIN contains at least 6 digits and that the
>    value is correct. Fexco recommends submitting 11 digits where
>    available for optimal accuracy.
> 2. If you are sending only 6 digits in the BIN field, add the
>    remaining card digits (7 to 11) in the `cid` parameter (Rate Service
>    Classic and Rate Service Connect) or the `CID` tag (ISO).
> 3. If the card remains unrecognized after verifying the BIN,
>    process the transaction in the merchant's base currency. Not
>    all card issuers are supported for DCC, and cards excluded
>    under card scheme rules are not eligible.

> [accordion] Unsupported card type (code 8)
>
> The ISO API returns response code `8`, or Rate Service Connect
> returns error code `8`.
>
> ### Why this happens
>
> The card scheme is not supported for DCC. DCC is available only
> for Visa, Mastercard, and Maestro payment cards.
>
> ### How to fix
>
> No corrective action is needed. Process the transaction in the
> merchant's base currency. Cards from other schemes (for example,
> AMEX, Diners, JCB) are not eligible for DCC.

> [accordion] Contactless transaction below the lower limit (code 97)
>
> The ISO API returns response code `97`, or Rate Service Connect
> returns error code `97`.
>
> ### Why this happens
>
> The transaction amount is at or below the contactless
> Transaction Lower Limit (TLL) configured for the merchant. The
> TLL is an optional per-MID setting that prevents DCC from being
> offered on low-value contactless transactions. This applies only
> when the `posentrymode` value indicates a contactless
> transaction (PAN capture method `07` or `91`).
>
> ### How to fix
>
> No corrective action is needed for the current transaction.
> Process it in the merchant's base currency. If you believe the
> TLL threshold is set too high for your use case, contact your
> Fexco project manager to adjust it.

> [accordion] Foreign card, DCC not available (code 99)
>
> The ISO API returns response code `99`, or Rate Service Connect
> returns error code `99`.
>
> ### Why this happens
>
> DHS recognized the card as a foreign card, but the specific
> currency of the card is not supported for DCC by the merchant's
> configuration.
>
> ### How to fix
>
> Process the transaction in the merchant's base currency. If you
> expect this currency to be supported, verify the merchant's DCC
> configuration with your Fexco project manager.

## Request fails or returns an error

> [accordion] Missing baseamount parameter (HTTP 400)
>
> The Rate Service Classic API returns HTTP `400` with the message "You have
> to specify 'baseamount'".
>
> ### Why this happens
>
> The `dccoffers` resource was called without the required
> `baseamount` query parameter, or the parameter value is empty.
> For ISO, the equivalent is response code `10` (Invalid
> Base Amount).
>
> ### How to fix
>
> Include `baseamount` in the query string with a valid numeric
> value in minor units per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217). The value must include the
> decimal point.
>
> ```
> dccoffers?bin=41017212345&baseamount=123.45&posentrymode=071
> ```

> [accordion] Invalid message format (code 2 or 30)
>
> The ISO API returns response code `2` or `30`. The
> `REFERENCENUMBER` in the response may contain `Null`.
>
> ### Why this happens
>
> The request message has structural or syntactical errors. XML
> tags may be missing, misspelled, or in the wrong case.
>
> ### How to fix
>
> 1. For XML over TCP/IP, verify that all tag names are uppercase
>    (for example, `CARDRATEREQUEST`, `BASEAMOUNT`). Tag names
>    are case-sensitive.
> 2. Confirm that all mandatory fields are present.
>    `REFERENCENUMBER`, `CARDID`, `MERCHANTID`, and `ACQUIRER`
>    are mandatory for card rate requests. `FGNCURCODE` is
>    mandatory for merchant rate requests.
> 3. Validate your XML message against the card rate or merchant
>    rate XSD provided by Fexco.

> [accordion] No such merchant (HTTP 404)
>
> The Rate Service Classic API returns HTTP `404` with the message "No such
> Merchant". For ISO, the equivalent is response code
> `4` (Unknown Acquirer or Merchant).
>
> ### Common causes
>
> * The merchant ID is misspelled or incorrectly formatted.
> * The merchant has not been boarded or has been deactivated.
> * The acquirer ID does not match the boarded merchant's
>   acquirer.
>
> ### How to fix
>
> 1. Confirm that the `$MERCHANT_ID` in your request URL matches
>    the Merchant Originator Tag (MID) assigned during boarding.
>    The value is case-sensitive and alphanumeric, up to 16
>    characters.
> 2. Confirm that the `$ACQUIRER_ID` matches the three-letter code
>    assigned by Fexco. For Rate Service Classic, this is a path segment. For
>    Rate Service Connect, this is the `x-acquirer-id` header.
> 3. Verify that the merchant is active and has not been
>    deactivated. See
>    [Reactivate a merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/reactivate-merchant.md)
>    if the merchant needs to be restored.

## Request fails with authentication or connection error

> [accordion] 401 Unauthorized (Rate Service Connect)
>
> The Rate Service Connect API returns HTTP `401 Unauthorized`.
>
> ### Common causes
>
> * The JWT token has expired. JWTs have a limited validity
>   window.
> * The `x-acquirer-id` header does not match the Organisation
>   (O) field in the client certificate.
> * The certificate used to sign the JWT has not been registered
>   with Fexco.
> * The `Authorization` header format is incorrect. There must be
>   exactly one space after `Bearer`.
>
> ### How to fix
>
> 1. Generate a new JWT using your current private key and client
>    certificate. Ensure the token has not expired.
> 2. Confirm that the `x-acquirer-id` header matches the
>    Organisation (O) field in the client certificate you used to
>    sign the JWT.
> 3. Confirm that the certificate you are using was signed by
>    Fexco and has not expired. See
>    [Certificate and JWT authentication](https://docs.fexco.com/dcc/api-reference/authentication/jwt-pki.md)
>    for the full setup process.

> [accordion] No response received over a persistent ISO 8583 connection
>
> The client sends an ISO 8583 rate request over an existing socket
> but receives no response. The read returns end of stream or fails
> with a connection reset error, and no DCC offer is presented.
>
> ### Why this happens
>
> DHS listens on port `8583` for incoming connection requests. Each
> time a client opens a connection, DHS creates a new socket,
> managed by a dedicated thread from a pool sized to handle
> simultaneous connections. The socket remains open and handles
> requests from the client until one of the following occurs:
>
> * **Connection reset**: the client explicitly closes its side of
>   the connection.
> * **Socket timeout**: the client sends no data within the socket
>   timeout window, and DHS closes the socket.
>
> The socket timeout is set to 5 seconds by default. If your
> integration keeps a socket open between transactions and the
> connection is idle for longer than 5 seconds, DHS closes the
> socket. DHS does not send a response when this happens. The next
> request written to the closed socket is not processed, and the
> client receives no response.
>
> ### How to fix
>
> Use one of the following approaches:
>
> 1. **Open a new socket for each request**, and close it once the
>    response is received.
> 2. **Reconnect on failure**: if a write or read on an existing
>    socket fails or returns end of stream, open a new socket and
>    resend the request.
> 3. **Keep the connection alive**: send 0800 network management
>    (echo) messages at an interval shorter than the socket timeout,
>    for example every 4 seconds.
>
> In addition:
>
> * Read the 2-byte length header and the response body in full
>   before parsing. A single read may return only part of the
>   message.
> * Log connection errors rather than discarding them, so that
>   dropped connections can be identified.
> * Verify that your system can reach the DHS host IP address and
>   port. DHS only accepts connections from pre-agreed IP
>   addresses.

## Server returns a 500 error or response code 1

> [accordion] 500 Internal Server Error or response code 1
>
> The Rate Service Classic API returns HTTP `500`, or the ISO API
> returns response code `1`.
>
> ### Why this happens
>
> An unexpected error occurred on the DHS server. For Rate Service Classic,
> this can also indicate a malformed URL (for example, double
> slashes in the path).
>
> ### How to fix
>
> 1. For Rate Service Classic, verify that the URL does not contain double
>    slashes, missing path segments, or other formatting errors.
> 2. If the URL is correct, retry the request after a short delay.
>    A transient server issue may resolve itself.
> 3. If the error persists, contact your Fexco project manager
>    with the `timestamp` and `message` from the error response
>    (Rate Service Classic) or the `REFERENCENUMBER` from the response
>    (ISO).

## Rate offer expires or becomes unavailable

> [accordion] Rate offer has expired
>
> The cardholder did not respond before the `expiry` timestamp in
> the rate offer.
>
> ### Why this happens
>
> Every DCC rate offer has a limited validity window. The rate is
> built from the most recently sourced wholesale rate at the time
> of the request. Once the expiry passes, the offer must not be
> used.
>
> ### How to fix
>
> Discard the expired offer and send a new rate request with the
> same parameters. Present the new offer to the cardholder. See
> [Handle rate expiry](https://docs.fexco.com/dcc/guides/rate-service/rate-expiry.md) for
> detailed guidance.

> [accordion] 409 Conflict — rate no longer available (Rate Service Connect)
>
> The Rate Service Connect API returns HTTP `409 Conflict`.
>
> ### Why this happens
>
> The underlying exchange rates are being refreshed, or the
> external rate service is temporarily unavailable. The rate
> that was available when the request was made is no longer
> valid.
>
> ### How to fix
>
> Wait a short time and retry the request. If the `409`
> response persists, contact your Fexco project manager.

## Still having issues?

If you have worked through the steps above and the issue persists,
contact your Fexco project manager with:

* Your acquirer ID and merchant ID.
* The API method you are using (Rate Service Classic, Rate Service Connect, XML, or
  ISO 8583).
* The environment (production or cert).
* The request URL or message.
* The timestamp of the request.
* The full error response or response code.

## Next steps

* [Request a DCC offer (Rate Service Classic)](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-rate-service-classic.md):
  review the Rate Service Classic request format and error responses.
* [Request a DCC offer (Rate Service Connect)](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-rate-service-connect.md):
  review the Rate Service Connect request format and error handling.
* [Request a DCC offer (ISO 8583)](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-iso.md):
  review the ISO 8583 message format.


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