Skip to main content

​
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: 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.
the full response envelope (code, message, messageDetail, data) is described in Card issuing and card orders; this page is only about errorCode and errorReason.
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; 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.
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:
The status sequences and what COMPLETED means are described in Webhook events and data structures. 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:

​
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 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
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.
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; a new Sumsub share token is usually not required.

​
Virtual-to-physical error codes (type=VIRTUAL_TO_PHYSICAL)

This type has a single failure code with no further breakdown. Read errorReason for the specific failure. See Physical card for details.

​
Card replacement error codes (type=REPLACEMENT)

This type has a single failure code with no further breakdown. The replacement operation is covered in 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.
“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).

​
Next steps