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

# Card application error codes

> The card application error codes from the original data dictionary, broken out into the card domain.

## Guide

Whether a card order fails on an upfront environment check, on a conflict in the customer data, or deep inside KYC review or card network issuing, a single `errorCode` field tells you which of three things to do: change a parameter and resubmit, ask the user to supply more documents, or accept a final decision and hand it to support. Every failed application turns into a clear next action instead of a vague "card application failed". As a licensed issuer, DCS normalizes the failure reasons of all three card order types (virtual card application, virtual-to-physical conversion and card replacement) into one stable set of `errorCode` values that partners can consume directly in their own products.

### Where the error code appears

When a card order moves to `status=FAILED`, the order response carries a pair of fields describing why:

| Field         | Type   | Description                                                                               |
| ------------- | ------ | ----------------------------------------------------------------------------------------- |
| `errorCode`   | String | The normalized failure reason code; the possible values are listed in the tables below    |
| `errorReason` | String | The human-readable text that goes with `errorCode`, which may be phrased for the end user |

When a card order is `status=FAILED`, `cardId` in `data` is empty and only then do `errorCode` and `errorReason` carry values. For example, `errorCode=INVALID_POA` is a case the user can fix by resubmitting documents, and it comes with `needExtraInfo=true` (see "Document resubmission" below). The `data` fields are defined in [Card issuing and card orders](./card-issuing).

<Note>
  the full response envelope (`code`, `message`, `messageDetail`, `data`) is described in [Card issuing and card orders](./card-issuing); this page is only about `errorCode` and `errorReason`.
</Note>

The pair appears in the two places below with **identical values**, so you can read whichever channel suits you:

* **Query card order detail** (you pull): see [Card issuing and card orders](./card-issuing); when `status=FAILED` the response carries `errorCode` and `errorReason`.
* **CARD\_ORDER webhook** (we push): DCS notifies you whenever a card order changes status, and `data` carries the same `errorCode` and `errorReason`. For the structure, see [Webhook events and data structures](../webhooks/events-and-schema).

> **Who does what**: the normalization is done by **DCS**. You never have to deal with the raw failure codes of the underlying KYC provider (Sumsub, for instance) or of the card network; you only integrate against the single set of `errorCode` values in the tables below. Mapping the raw codes onto this set is DCS's job, and DCS notifies partners in advance whenever a new value is added.

### How card order status relates to the failure reason

The possible `status` values **depend on the card order type (`type`)**. A failure reason only appears once the order reaches `FAILED`; non-final states such as `PENDING` must never be read as a failure:

| `type`                                                | Status sequence, intermediate and final                                             | When `FAILED` appears                                        |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `VIRTUAL` (virtual card application)                  | `PENDING → CUSTOMER_PASS → KYC_PASS → CHANNEL_CUSTOMER_PASS → COMPLETED` / `FAILED` | As soon as any stage does not pass, most often the KYC stage |
| `VIRTUAL_TO_PHYSICAL` (virtual card to physical card) | `PENDING → PHYSICAL_SETTING_COMPLETED → COMPLETED` / `FAILED`                       | When card production or the card network step fails          |
| `REPLACEMENT` (card replacement)                      | `PENDING → COMPLETED` / `FAILED`                                                    | When the replacement step fails                              |

> The `status` sequences and what `COMPLETED` means are described in [Webhook events and data structures](../webhooks/events-and-schema). `COMPLETED` means the card was issued, and only then does `cardId` carry a value.

***

## Virtual card application error codes (`type=VIRTUAL`)

Failures on a virtual card application fall into two groups: **partner-side and environment errors**, which you can fix by changing a parameter or checking your data before resubmitting, and **KYC rejections**, which make up the vast majority and come out of the underlying KYC review.

### Partner-side and environment errors

These codes have nothing to do with KYC. Most of them are request parameter problems or idempotency conflicts, and **the partner can fix them alone**:

| `errorCode`               | Description                                                  | Retryable | What the partner should do                                                                                                                       | Resubmission possible |
| ------------------------- | ------------------------------------------------------------ | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------: |
| `OPERATION_NOT_SUPPORT`   | Operation not supported, for example a duplicate application |     ❌     | Check whether you are raising the same request twice for the same customer or order; deduplicate in your own logic instead of retrying in a loop |           No          |
| `EMAIL_ALREADY_EXISTS`    | Email address already exists                                 |     ⚠️    | A customer is already registered with this email; use the existing `customerId` or a different address                                           |           No          |
| `EMAIL_INVALID`           | Email address is invalid                                     |     ⚠️    | Ask the user for a different email address and resubmit                                                                                          |           No          |
| `PHONE_ALREADY_EXISTS`    | Phone number already exists                                  |     ⚠️    | A customer is already registered with this phone number; reuse that customer or use a different number                                           |           No          |
| `CUSTOMER_REF_NOT_UNIQUE` | Customer reference is not unique                             |     ✅     | Use a globally unique `customerRef` and resubmit                                                                                                 |           No          |
| `CUSTOMER_INFO_INVALID`   | Customer information invalid                                 |     ✅     | Check the format of the phone number, email and other fields, then resubmit                                                                      |           No          |
| `CARD_CREATION_FAILED`    | Card creation failed                                         |     ⚠️    | Issuing failed on the card network side; retry later and contact DCS if it keeps failing                                                         |           No          |

### KYC rejections

Almost every `FAILED` on a virtual card application comes from a KYC rejection. **These `errorCode` values share exactly one source with the [KYC rejection codes](../kyc/kyc-reject-codes) page and have identical values.** That page already groups them into business buckets with the three columns "retryable", "what the user should do" and "resubmission possible" plus integration guidance, so treat it as the authoritative reference rather than duplicating the handling here.

The list below only enumerates, bucket by bucket, the KYC rejection codes that can appear in a card order `errorCode` (the descriptions follow the data dictionary verbatim). For the action to take, follow the bucket through to the KYC page:

* **Document image quality (fixable: have the user reshoot or re-upload)**: `POOR_IMAGE_CAPTURE_QUALITY`, `DOCUMENT_DAMAGED_OR_UNCLEAR`, `POOR_PHOTO_QUALITY`, `LOW_DOCUMENT_QUALITY`, `DOCUMENT_PAGE_MISSING`, `INCOMPLETE_DOCUMENT_SUBMISSION`, `BACK_SIDE_MISSING`, `FRONT_SIDE_MISSING`, `UNSUPPORTED_DOCUMENT_FORMAT`, `INVALID_UPLOAD_TYPE`, `SCREENSHOT_DETECTED`, `COLORED_COPY_REQUIRED`, `ORIGINAL_DOCUMENT_REQUIRED`
* **Document validity and type (some are fixable)**: `EXPIRED_DOCUMENT`, `UNSUPPORTED_DOCUMENT_TYPE`, `UNSUITABLE_DOCUMENT_SUBMITTED`, `UNSUPPORTED_OR_INVALID_DOCUMENT_TEMPLATE`, `INVALID_IDENTIFICATION_DOCUMENT`, `DOCUMENT_VALIDATION_FAILED`, `UNSUPPORTED_LANGUAGE`, `UNSUPPORTED_DOCUMENT_LANGUAGE`
* **Missing supporting material or incomplete data (fixable through a resubmission)**: `ADDITIONAL_SUPPORTING_DOCUMENT_REQUIRED`, `MORE_SUPPORTING_DOCUMENTS_REQUIRED`, `INCOMPLETE_APPLICANT_DATA`
* **Information mismatch (fixable: check the data)**: `INFORMATION_MISMATCH`, `PROFILE_INFORMATION_MISMATCH`, `SUBMITTED_DATA_MISMATCH`, `DATABASE_INFORMATION_MISMATCH`, `ADDRESS_INFORMATION_MISMATCH`, `AGE_MISMATCH`, `INVALID_POA`, `INVALID_PROOF_OF_ADDRESS`, `INVALID_POI`, `INVALID_PROOF_OF_IDENTITY`, `INVALID_PROOF_OF_PAYMENT`
* **Face and liveness verification (some are fixable)**: `FACE_VERIFICATION_FAILED`, `LIVENESS_CHECK_FAILED`, `THIRD_PARTY_ASSISTANCE_DETECTED`, `IDENTITY_OWNERSHIP_VALIDATION_FAILED`, `MULTIPLE_PERSONS_DETECTED`
* **Compliance and risk decisions, final (do not retry; show a neutral message and never echo the compliance reason)**: `NAME_SCREENING_HIT`, `EDD_REJECTED`, `SUSPICIOUS_APPLICATION_BEHAVIOR`, `SECURITY_VALIDATION_FAILED`, `SECURITY_SCREENING_FAILED`, `SCREENING_UNSUCCESSFUL`, `COMPLIANCE_RESTRICTION`, `SUMSUB_BLOCKED`, `BLOCKED`
* **Eligibility and regional restrictions (final, and dependent on your programme configuration)**: `OUT_OF_ELIGIBLE_COUNTRIES`, `REGION_OR_RESIDENCY_RESTRICTION`, `ELIGIBILITY_OR_REGION_RESTRICTION`, `FAIL_TO_MEET_DCS_REQUIREMENT`, `FAIL_TO_MEET_PARTNER_REQUIREMENT`, `ELIGIBILITY_REQUIREMENT_NOT_MET`, `AGE_REQUIREMENT_NOT_MET`, `USA_TAX_RESIDENT`, `INCOME_REQUIREMENT_NOT_MET`, `CREDIT_ASSESSMENT_FAILED`, `UNSUPPORTED_PRODUCT`
* **Duplicates and suspected fraud (final)**: `DUPLICATE_APPLICATION_DETECTED`, `INVALID_OR_DUPLICATE_SUBMISSION`, `REAPPLICATION_PERIOD_NOT_MET` (the cooling-off period after closing a card has not elapsed, so do not prompt a reapplication)
* **Validation could not complete or the data source failed (depends on the case, usually a system-side issue to retry later)**: `APPLICANT_DATA_VALIDATION_FAILED`, `APPLICANT_DATA_NOT_FOUND`, `VERIFICATION_INCOMPLETE`, `VERIFICATION_CHECK_UNAVAILABLE`, `CONNECTIVITY_OR_SERVICE_ERROR`, `DATA_SOURCE_UNAVAILABLE`, `TIMEOUT`, `OTHER_VALIDATION_ISSUE`
* **Share token and reusable KYC (mostly retryable)**: `INVALID_SHARE_TOKEN`, `SHARE_TOKEN_FAILED`, `INVALID_VERIFICATION_SESSION`, `VERIFICATION_PROCESSING_TIMEOUT`, `REUSABLE_INCOMPATIBLE_DOCUMENT`, `REUSABLE_KYC_NOT_ENABLED`, `REUSABLE_VERIFICATION_NOT_ELIGIBLE`
* **Submission not completed inside the time window (`TIMEOUT_*`, retryable)**: `TIMEOUT_INVALID_PROOF_OF_IDENTITY`, `TIMEOUT_INVALID_PROOF_OF_ADDRESS`, `TIMEOUT_DOCUMENT_VALIDATION_FAILED`, `TIMEOUT_DOCUMENT_PAGE_MISSING`, `TIMEOUT_EXPIRED_DOCUMENT`, `TIMEOUT_POOR_PHOTO_QUALITY`, `TIMEOUT_SCREENSHOT_DETECTED`, `TIMEOUT_FACE_VERIFICATION_FAILED`, `TIMEOUT_AGE_REQUIREMENT_NOT_MET`, `TIMEOUT_ELIGIBILITY_OR_REGION_RESTRICTION`, `TIMEOUT_SUMSUB_BLOCKED`
* **Other**: `UNSATISFACTORY_DOCUMENT`, `OTHERS`

<Warning>
  **Do not read `TIMEOUT_*` by its suffix**: this group only means the user did not complete the submission to Sumsub within the time window. The suffix merely says which step it timed out on and does **not** mean that check actually failed. Treat it as a timeout: have the user start again and finish promptly, rather than asking them to re-supply whatever the suffix names.
</Warning>

> **Document resubmission**: when KYC is rejected over POA or missing supporting material (`INVALID_POA` or `ADDITIONAL_SUPPORTING_DOCUMENT_REQUIRED`, for example), `needExtraInfo=true` in the card order response or webhook means more material is needed. Submit it through the resubmission path in [Card issuing and card orders](./card-issuing); **a new Sumsub share token is usually not required**.

***

## Virtual-to-physical error codes (`type=VIRTUAL_TO_PHYSICAL`)

| `errorCode`                  | Description                           | Retryable | What the partner should do                                                                                                 | Resubmission possible |
| ---------------------------- | ------------------------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------- | :-------------------: |
| `VIRTUAL_TO_PHYSICAL_FAILED` | Virtual-to-physical conversion failed |     ⚠️    | Card production or the card network step failed; check the shipping details and retry, and contact DCS if it keeps failing |           No          |

> This type has a single failure code with no further breakdown. Read `errorReason` for the specific failure. See [Physical card](./physical-card) for details.

***

## Card replacement error codes (`type=REPLACEMENT`)

| `errorCode`               | Description             | Retryable | What the partner should do                                                                                                                     | Resubmission possible |
| ------------------------- | ----------------------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------: |
| `CARD_REPLACEMENT_FAILED` | Card replacement failed |     ⚠️    | The replacement step failed; check the status of the original card and the replacement reason, then retry, and contact DCS if it keeps failing |           No          |

> This type has a single failure code with no further breakdown. The replacement operation is covered in [Card management](./card-management).

***

### Integration guidance

* **Branch on `errorCode`, never on the `errorReason` text**: `errorReason` may be reworded between releases or localized. Keep your program logic on `errorCode` and use `errorReason`, or your own copy, for display.
* **Always have a fallback for unknown codes**: values are added to and removed from these tables as compliance policy and card network capabilities change. Route any `errorCode` you do not recognize into a default branch (handle it as `OTHERS` and raise an alert) so a new code never breaks your front end.
* **Tell non-final states apart from failures**: only read a failure reason when `status=FAILED`. Intermediate states such as `PENDING` must not be treated as failures, or you will wrongly block orders that are still under review.
* **Never retry a final code in a loop**: the compliance, eligibility, duplicate and fraud codes (marked ❌) are final. Resubmitting achieves nothing and may trip risk controls; show a neutral message and point the user to support.

<Note>
  "retryable" and "resubmission possible" in the tables are integration guidance. Your program logic should key off `errorCode` together with `status=FAILED`, with a fallback for any `errorCode` outside the known list (handle it as `OTHERS` and raise an alert).
</Note>

***

## Next steps

* Issuing a card, checking card order status and reading `errorCode`: see [Card issuing and card orders](./card-issuing).
* The full handling of every KYC rejection code, covering retryability, what the user should do and whether a resubmission helps: see [KYC rejection codes](../kyc/kyc-reject-codes).
* Receiving `FAILED` notifications and parsing the webhook `data` field: see [Webhook events and data structures](../webhooks/events-and-schema).