> ## 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 boarding errors

> Diagnose and resolve common merchant boarding problems across Boarding API and XML methods.

Use this page when a boarding request fails, returns unexpected
results, or you are not sure what went wrong. 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 credentials: OAuth token (Boarding API) or SFTP
  credentials (XML).
* Check that your acquirer ID matches the value Fexco provided
  during onboarding.
* Confirm the request or file matches the documented format for
  your boarding method.

## File and request issues

> [accordion] Entire XML file is rejected
>
> No merchants in the file are processed. The response file is
> empty or not generated.
>
> **Common causes**
>
> * A required XML element is missing or empty.
> * Elements appear in the wrong order.
> * A special character like `&` is used without an XML entity
>   reference (use `&` instead).
> * A data field exceeds the maximum length defined in the XSD.
> * The `xsi:schemaLocation` attribute is missing from the root
>   element.
> * The encoding declaration is missing or incorrect.
>
> **How to fix**
>
> 1. [Validate the file against the Boarding File Upload XSD](https://docs.fexco.com/dcc/guides/merchant-boarding/validate-xml.md).
> 2. Fix each error the validator reports.
> 3. Re-validate until the file passes with no errors.
> 4. Upload the corrected file to your SFTP directory.
>
> This only applies to XML submissions. Boarding API requests
> do not have file-level rejection.

> [accordion] One or more merchants rejected
>
> The file or batch was accepted, but some merchants failed. Other
> merchants in the same submission were processed normally.
>
> **What you are seeing**
>
> * XML: the response file shows `400` in the `Status Code`
>   column for the failed merchants.
> * Boarding API: the summary endpoint shows `FAILED` in the `status`
>   field for the failed merchants.
>
> **Common causes**
>
> * Merchant already exists (duplicate ID).
> * Template not found (wrong `fileGroupId`, `templateId`, or rate
>   margin name).
> * Unknown acquirer ID.
> * Invalid or missing required fields.
>
> **How to fix**
>
> 1. Check the error code on the failed merchant.
> 2. Fix the data for the failed merchants only.
> 3. Resubmit only the failed merchants. Do not resubmit merchants
>    that succeeded, as this causes duplicate errors.

> [accordion] Operation succeeds with warnings
>
> The merchant was created, updated, or deactivated, but the
> response includes warning codes.
>
> **What you are seeing**
>
> * XML: the response file shows `200` in the `Status Code`
>   column, but the `Warning List` column is not empty.
> * Boarding API: the summary endpoint shows
>   `COMPLETED_WITH_WARNINGS` in the `status` field.
>
> **What this means**
>
> Warnings do not block the operation. The merchant was processed,
> but part of the submitted data may not have been applied as
> expected. For example, a terminal ID you tried to add may
> already exist, or an account manager name did not match.
>
> **How to fix**
>
> 1. Look up the warning code in the response file.
> 2. Decide if the warning affects your intended result.
> 3. If you need to change a rate margin or base currency on an
>    existing originator, delete the originator and add a new one
>    with the correct values.

> [accordion] Request times out or no response received
>
> You submitted a request but did not receive a response or
> confirmation file.
>
> **Boarding API**
>
> 1. Poll
>    [Get boarding status](https://docs.fexco.com/dcc/api-reference/boarding-rest/get-boarding-status.md).
>    The batch may still be processing.
> 2. If polling returns no result after 1 hour, contact your Fexco
>    project manager with the `boardingId`.
>
> **XML**
>
> 1. Check your SFTP `Outgoing` folder for a response file.
>    Processing normally takes up to 30 minutes. Large files may
>    take up to approximately 1 hour.
> 2. Confirm the file was uploaded to the correct SFTP directory
>    (`Incoming` folder).
> 3. Verify the file follows the
>    [naming convention](https://docs.fexco.com/dcc/guides/merchant-boarding/board-xml.md#file-naming-convention).
>    Files with incorrect names may not be picked up.
> 4. If no response file appears after 1 hour, contact your Fexco
>    project manager with the file name and upload timestamp.

## Authentication and connection issues

> [accordion] 401 Unauthorized (Boarding API)
>
> Your boarding request is rejected before any data is processed.
>
> **Common causes**
>
> * OAuth token is invalid or has expired. Use the `expires_in` value
>   returned in the token response to determine when it expires.
> * The `Authorization` header is missing or incorrectly
>   formatted.
> * The `x-acquirer-id` header does not match your acquirer code.
>
> **How to fix**
>
> 1. Request a new OAuth token. See
>    [OAuth authentication](https://docs.fexco.com/dcc/api-reference/authentication/oauth.md).
> 2. Check that the `Authorization` header uses the format
>    `Bearer YOUR_ACCESS_TOKEN` with a space after `Bearer`.
> 3. Verify the `x-acquirer-id` header matches the acquirer code
>    Fexco provided during onboarding.

> [accordion] 403 Forbidden (Boarding API)
>
> The server recognized your credentials but rejected the request.
>
> **Common causes**
>
> * Your credentials do not have permission for this operation.
> * The acquirer ID does not match your OAuth token.
>
> **How to fix**
>
> 1. Verify the `x-acquirer-id` header matches the acquirer
>    associated with your OAuth credentials.
> 2. Contact your Fexco project manager to confirm your
>    credentials have the correct permissions.

> [accordion] SFTP connection refused or times out
>
> You cannot connect to the Fexco SFTP server to upload or
> download files.
>
> **Common causes**
>
> * SFTP credentials are incorrect.
> * Your IP address is not whitelisted.
> * You are connecting to the wrong SFTP server.
>
> **How to fix**
>
> 1. Confirm your SFTP username and password (or SSH key) are
>    correct.
> 2. Verify your outbound IP address is whitelisted with Fexco.
>    See
>    [Security setup](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md).
> 3. Check that you are connecting to the correct SFTP server for
>    your environment.
> 4. If the issue persists, contact your Fexco project manager
>    with your IP address and the error message.

## Server errors

> [accordion] 500 Internal Server Error or error code 19
>
> A `500` status code (XML) or error code `19` (all methods)
> means an unexpected server-side error occurred. This is not
> caused by your data.
>
> **How to fix**
>
> Do not resubmit the same request until the issue is confirmed
> resolved. Contact your Fexco project manager with:
>
> * The request ID or boarding ID.
> * The timestamp of the request.
> * The file name (for XML submissions).
> * The full error response, if available.

## Merchant state issues

> [accordion] Merchant is deactivated and cannot be updated
>
> You are trying to update a merchant but receive error code `9`
> (merchant is inactive).
>
> **Why this happens**
>
> The merchant was previously deactivated. Updates cannot be
> applied to inactive merchants.
>
> **How to fix**
>
> [Reactivate the merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/reactivate-merchant.md)
> through Fexco Merchant Operations before submitting the update.

> [accordion] Merchant already exists (duplicate ID)
>
> You are trying to create a merchant but receive error code `6`.
>
> **Why this happens**
>
> A merchant with this ID is already in the system. Each merchant
> ID must be unique within your acquirer.
>
> **How to fix**
>
> * If you want to change the existing merchant, submit an update
>   (XML only) instead of a create. See
>   [Update a boarded merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/update-merchant.md).
> * If you want to create a new merchant, use a different
>   merchant ID.

## Still having issues?

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

* Your acquirer ID.
* The boarding method you are using (Boarding API or XML).
* The environment (production or cert).
* The request ID, boarding ID, or file name.
* The timestamp of the request.
* The full error or warning response.


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