Authorization declines and error codes - DCS Technical Documentation

📄 Guide

Whether the platform you are integrating is an exchange, a wallet or something else, you can rely on one standardised set of error codes to locate a problem fast: every DCS API response uses the same format, and decline reasons under Partner-Managed come back as stable error codes that your own system can branch on and turn into user guidance. As a licensed issuer with its own BIN, DCS keeps error semantics consistent across authorization, settlement and reconciliation. This page groups the error codes into buckets by scenario and, for each bucket, adds guidance on whether to retry, what the user should do and whether documents can be resubmitted. It helps you separate system-level errors, parameter and business validation errors and declines under Partner-Managed.

The common response envelope

Every endpoint, successful or not, returns the same outer JSON envelope:

{
  "code": "DAPI_CARD_ORDER_REF_ALREADY_EXISTS",
  "message": "card order ref already exists",
  "messageDetail": null,
  "data": null
}

Field	Type	Description
`code`	string	The result code: on success it is the success indicator described below, and on failure it is one of the `DAPI_*` codes enumerated on this page
`message`	string	A short English description of the error, written for developers and not intended for display to end users
`messageDetail`	object \| null	An optional display object (with `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`, all strings) meant for front-end guidance; may be `null`
`data`	object \| null	Business payload; usually `null` on failure

Judge success or failure by code (SYS_SUCCESS on success, one of the DAPI_* codes on this page on failure). Do not branch on the message text, and do not assume messageDetail is always populated.

About the DAPI_ prefix: the codes on this page appear in the code field of the response envelope and always carry the DAPI_ prefix. Two other families do not, because they appear inside the business payload rather than the envelope: the card order’s data.errorCode (see Card application error codes) and the KYC ticket’s data.errorCode (see KYC rejection codes). Pick the right form based on where the value comes from.

The division of labour between messageDetail and message, and whether messageDetail is mandatory on failure, is not yet settled in the documentation.

Error codes by bucket

The tables below sort every DAPI_* code from the published error code list into buckets by scenario. Each bucket carries one set of handling guidance, and any code that needs a note of its own is called out inside its bucket.

1. System-level errors (the partner cannot fix these)

ErrorCode	Message	Meaning
`DAPI_SYSTEM_ERROR`	System error	Internal system error
`DAPI_OPERATION_NOT_SUPPORT`	operation not support	The operation is not supported
`DAPI_PERMISSION_DENIED`	permission denied	Insufficient permissions

Retry? DAPI_SYSTEM_ERROR can be retried after a back-off; retrying DAPI_OPERATION_NOT_SUPPORT or DAPI_PERMISSION_DENIED is pointless.
What the user should do: show the end user a message along the lines of “the system is busy, please try again later”.
Resubmit documents? Not applicable.
Partner action: if it persists, contact DCS to investigate and confirm which capabilities your account has been enabled for.

2. Authentication and signature errors

ErrorCode	Message	Meaning
`DAPI_API_KEY_EMPTY`	API Key cannot be empty	The API key header is missing
`DAPI_INVALID_API_KEY`	Api Key is invalid	The API key is invalid
`DAPI_SECRET_KEY_EMPTY`	Secret Key cannot be empty	The secret key is missing
`DAPI_SIGNATURE_ERROR`	signature error	Signature verification failed
`DAPI_CALCULATE_SIGNATURE_ERROR`	Failed to calculate hmac-sha256	The server failed to compute the HMAC-SHA256 signature
`DAPI_TIMESTAMP_EMPTY`	request timestamp cannot be empty	The request timestamp is missing
`DAPI_TIMESTAMP_FORMAT_ERROR`	incorrectly formatted request timestamp	The timestamp format is wrong
`DAPI_TIMESTAMP_EXPIRED`	request timestamp has expired	The timestamp has expired (replay protection)
`DAPI_NONCE_ILLEGAL`	nonce illegal	The nonce is not valid (replay protection)

Retry? Yes, once the authentication headers are corrected; DAPI_TIMESTAMP_EXPIRED needs a fresh timestamp and a new signature.
What the user should do: nothing, this is a server-side configuration issue on the partner side.
Resubmit documents? Not applicable.
Partner action: check the authentication headers and the signing rules item by item; see Authentication and signing.

The nonce range is [10000, 99999], and it is used together with the request timestamp for replay protection. Callers must not reuse a nonce, and should maintain a separate idempotency key for business write operations.

3. Parameter and permission validation errors

ErrorCode	Message	Meaning
`DAPI_SYS_ILLEGAL_PARAM`	System illegal param	Invalid parameter
`DAPI_UPLOAD_BUSINESS_TYPE_ERROR`	Wrong business type	Wrong upload business type

Retry? Yes, once the parameters are corrected.
What the user should do: nothing, this is a server-side integration issue.
Resubmit documents? Not applicable.
Partner action: correct the request body against the parameter table of the endpoint concerned.

4. User and enterprise errors

ErrorCode	Message	Meaning
`DAPI_ENTERPRISE_NOT_FOUND`	enterprise not found	The enterprise does not exist
`DAPI_CUSTOMER_NOT_FOUND`	customer not found	The user does not exist
`DAPI_CHANNEL_CUSTOMER_NOT_FOUND`	channel customer not found	The user does not exist on the channel side
`DAPI_CHANNEL_CUSTOMER_CREATE_FAILED`	channel customer create failed	Creating the user on the channel side failed
`DAPI_CUSTOMER_EMAIL_OR_PHONE_REQUIRED`	customer email or phone required	At least one of email or phone must be supplied
`DAPI_PHONE_INVALID`	invalid phone	The phone number format is wrong
`DAPI_EMAIL_INVALID`	invalid email	The email address is invalid
`DAPI_EMAIL_ALREADY_EXISTS`	email already exists	The email already exists
`DAPI_PHONE_ALREADY_EXISTS`	phone already exists	The phone number already exists
`DAPI_CUSTOMER_REF_NOT_UNIQUE`	customerRef not unique	The `customerRef` idempotency key is duplicated
`DAPI_ENTERPRISE_BALANCE_RECORD_NOT_EXISTS`	enterprise balance record not found	The enterprise balance record does not exist

Retry? Format errors (*_INVALID) can be retried once corrected; *_ALREADY_EXISTS and *_NOT_UNIQUE are idempotency or uniqueness conflicts, so use the existing record instead of creating another.
What the user should do: if the email or phone is malformed or already taken, guide the user to change it or confirm ownership.
Resubmit documents? Not applicable, these are creation-time validations.
Partner action: DAPI_CUSTOMER_REF_NOT_UNIQUE usually comes from a duplicate submission; query the existing user instead.

5. KYC, ticket and EDD errors

ErrorCode	Message	Meaning
`DAPI_TICKET_REF_REPEATED`	ticketRef repeated	The ticket idempotency key is duplicated
`DAPI_EXIST_ONGOING_TICKET_ERROR`	There is an ongoing work order	A ticket is already in progress
`DAPI_CARD_ORDER_KYC_INFO_INVALID`	kyc info invalid	The KYC information is invalid
`DAPI_CARD_ORDER_KYC_VERIFY_FAILED`	kyc verify failed	KYC verification did not pass
`DAPI_REQUEST_REJECTION_ERROR`	EDD application rejected	The enhanced due diligence (EDD) application was rejected
`DAPI_TICKET_APPLY_LIMIT_EXCEEDED`	Ticket application exceeds the limit	The KYC ticket application hit the intake rate limit

Retry? With DAPI_EXIST_ONGOING_TICKET_ERROR, wait for the existing ticket to close before starting another; with DAPI_TICKET_REF_REPEATED, use the existing ticket; DAPI_TICKET_APPLY_LIMIT_EXCEEDED needs a back-off before retrying, so do not resend immediately.
What the user should do: when KYC does not pass, guide the user to supply what the rejection reason asks for (POI or POA). A failed POA does not require a new Sumsub token; use the supplementary endpoint directly.
Resubmit documents? Yes. A KYC or EDD rejection normally lets the user supplement or update the materials and submit again.
Partner action: for the KYC flow and its state machine, see KYC flow.

KYC rejection reasons are returned through the KYC ticket’s data.errorCode / errorMessage; the full mapping is in KYC reject codes, so the direction of a resubmission can only be inferred from the ticket status and its text.

6. Card order and card configuration errors

ErrorCode	Message	Meaning
`DAPI_CARD_ORDER_REF_ALREADY_EXISTS`	card order ref already exists	The card order idempotency key is duplicated
`DAPI_CARD_ORDER_NOT_FOUND`	card order not found	The card order does not exist
`DAPI_CARD_ORDER_ID_INCORRECT_ERROR`	businessId is error, cardOrderId incorrect	The `cardOrderId` is incorrect
`DAPI_CARD_ORDER_PROFILE_NOT_FOUND` / `DAPI_CARD_PROFILE_NOT_FOUND`	card profile not found	The card profile does not exist
`DAPI_CARD_ORDER_CUSTOMER_INFO_INVALID`	customer info invalid	The user information in the card order is invalid
`DAPI_CARD_ORDER_CHANNEL_CUSTOMER_INVALID`	channel customer invalid	The channel-side user information is invalid
`DAPI_CARD_ORDER_CHANNEL_CARD_INVALID`	channel card invalid	The channel-side card information is invalid
`DAPI_CARD_ORDER_NOT_NEED_EXTRA_INFO`	card order does not need extra info	This card order needs no extra information
`DAPI_CARD_ORDER_VIRTUAL_TO_PHYSICAL_FAILED`	virtual to physical failed	Converting the virtual card to a physical card failed
`DAPI_CARD_PROFILE_NOT_SUPPORTING_COUNTRY_CODES`	Card profile not supporting country codes	The card profile does not support that country code
`DAPI_CARD_LAYOUT_NOT_FOUND`	card layout not found	The card layout does not exist
`DAPI_EXIST_NOT_FAILED_REPLACE_CARD_ORDER`	There are card replacement orders that are not accepted	An unfinished card replacement order exists
`DAPI_CARD_APPLY_LIMIT_EXCEEDED`	Card application exceeds the limit	The card application hit the intake rate limit, as when one user applies too often in a short window
`DAPI_REPLACE_CARD_APPLY_LIMIT_EXCEEDED`	card replacement application limit exceeded within 24 hours	Card replacement hit the 24-hour rate limit
`DAPI_VIRTUAL_TO_PHYSICAL_APPLY_LIMIT_EXCEEDED`	virtual to physical application limit exceeded within 24 hours	Virtual-to-physical conversion hit the 24-hour rate limit

Retry? Configuration errors (unsupported profile, layout or country code) need the configuration confirmed on the DCS side first, then a retry; for *_REF_ALREADY_EXISTS, use the existing order; DAPI_CARD_APPLY_LIMIT_EXCEEDED needs a back-off before retrying, so do not resend immediately.
What the user should do: usually nothing. Where a region is not supported, tell the user this card type is not available in their location for now.
Resubmit documents? Not applicable.
Partner action: use profileId in customer-facing card issuance (the enterprise balance query uses the synonymous field cardProfileId). There is no online query endpoint today; DCS assigns the value offline. Do not use the internal alias categoryId in a customer-facing integration.

7. Card management and card status errors

ErrorCode	Message	Meaning
`DAPI_CARD_NOT_FOUND`	card not found	The card does not exist
`DAPI_CARD_ID_INCORRECT_ERROR`	businessId is error, cardId incorrect	The `cardId` is incorrect
`DAPI_CARD_STATUS_NOT_ACTIVATED`	card status not activated	The card is not in the activated state
`DAPI_CARD_STATUS_NOT_FROZEN`	card status not frozen	The card is not in the frozen state
`DAPI_CARD_STATUS_NOT_WAITING_ACTIVE`	card status not waiting active	The card is not in the waiting-for-activation state
`DAPI_CARD_ACTIVATION_FAILED`	card activation failed	Card activation failed
`DAPI_CARD_NOT_EMBOSSED_ERROR`	Card not embossed: Activation not allowed before embossing	The physical card has not been embossed and cannot be activated before embossing
`DAPI_CARD_PIN_MUST_BE_FOUR_DIGIT_NUMBER`	The pin must be a four-digit number	The PIN must be four digits
`DAPI_CARD_TYPE_NOT_VIRTUAL`	card type is not virtual	The card is not a virtual card
`DAPI_CARD_TYPE_NOT_PHYSICAL`	card type is not physical	The card is not a physical card
`DAPI_ORIGINAL_CARD_STATUS_NOT_ACTIVATED`	original card status not activated	The original card is not activated (card replacement)
`DAPI_ORIGINAL_CARD_NOT_FOUND`	original card not found	The original card does not exist (card replacement)

Retry? State mismatch errors require moving the card into the right state before retrying; blind retries achieve nothing. The card state machine is in Card management.
What the user should do: on a PIN format error, prompt the user to enter four digits again; a card awaiting activation must be activated by the user first.
Resubmit documents? Not applicable.
Partner action: freeze and unfreeze share one endpoint, POST /open-api/card/v1/freeze, distinguished by the boolean freeze (true freezes, false unfreezes). Confirm the current card state before calling it.

8. Hosted page errors

ErrorCode	Message	Meaning
`DAPI_GUIDANCE_LINK_TYPE_INVALID`	guidance link type invalid	The guidance link type is invalid
`DAPI_GUIDANCE_LINK_PRE_VERIFIED_INVALID`	guidance link preVerified invalid	The `preVerified` value on the guidance link is invalid

Retry? Yes, once the hosted page parameters are corrected.
What the user should do: nothing, this is a parameter issue in how the partner generated the link.
Resubmit documents? Not applicable.

Declines under Partner-Managed (the important part)

Under Partner-Managed, the spending limits belong to the partner and the partner makes the authorization decision in real time. When a cardholder pays, DCS forwards the authorization request to the partner’s authorization callback URL (auth_url) and the partner approves or declines. When an authorization is declined, the reason is returned in the rejectReason field of the AUTHORISATION_RESULT webhook and the daily authorization report, always carrying the DAPI_ prefix (production example: "approveFlag":"D","rejectReason":"DAPI_SYSTEM_ERROR"). The complete enumeration:

`rejectReason`	When it occurs
`DAPI_CARD_STATUS_NOT_ACTIVATED`	The card was not in the `ACTIVATED` state when the authorization entered processing (not activated, frozen, blocked or invalid); checked for both outgoing and incoming authorizations
`DAPI_CARD_CONSUME_FROZEN`	The user’s KYC factor has expired, restricting spending (checked for outgoing authorizations only)
`DAPI_CARD_VELOCITY_LIMIT_CHECK_REJECT`	The velocity limit check did not pass
`DAPI_AUTH_ENTERPRISE_REJECT`	The partner returned an explicit decline in the authorization callback
`DAPI_AUTH_ENTERPRISE_TIMEOUT_REJECT`	The partner’s authorization callback timed out without a response
`DAPI_AUTH_INTERNAL_REJECT`	Internal system decline: signature verification failed, the request failed or the response was invalid; the card could not be found; an incremental authorization or reversal could not find the original authorization, or the currency did not match; the hold or release flow failed abnormally
`DAPI_AUTH_INSUFFICIENT_FUNDS_REJECT`	The preceding checks passed, but placing or releasing the hold on the enterprise ledger failed (insufficient balance)
`DAPI_SYSTEM_ERROR`	Fallback for an unexpected system error

The check order is fixed: card status → KYC spending restriction → velocity limit → enterprise callback → fund hold; when several conditions are hit at once, only the first one is returned.

Retry? An authorization decline is the outcome of a single transaction; the cardholder has to start again at the merchant. The partner must not retry the same authorization request server-side.
What the user should do: DAPI_AUTH_ENTERPRISE_REJECT usually means insufficient limit or a risk rule on the partner side, so the partner should explain it to the end user under its own rules (insufficient balance, over limit and so on).
Resubmit documents? Not applicable.
Partner action: for a timeout decline (*_TIMEOUT_REJECT), investigate the response latency of your authorization callback. In production the synchronous response window is 2.5 seconds, and the partner must reply within it.

The authorization request and response fields and the signing rules are in the authorization callback; for where rejectReason sits in the report files, see the authorization report. Finer business reasons such as insufficient balance, over-limit and restricted MCC are determined and recorded by the partner inside its own authorization logic.

Next steps

Once you have identified the error code, return to Transaction records to understand how Auth, Outstanding and Transaction relate, or go to Sandbox simulation to replay a declined authorization in the test environment.

​📄 Guide

​The common response envelope

​Error codes by bucket

​1. System-level errors (the partner cannot fix these)

​2. Authentication and signature errors

​3. Parameter and permission validation errors

​4. User and enterprise errors

​5. KYC, ticket and EDD errors

​6. Card order and card configuration errors

​7. Card management and card status errors

​8. Hosted page errors

​Declines under Partner-Managed (the important part)

​Next steps

📄 Guide

The common response envelope

Error codes by bucket

1. System-level errors (the partner cannot fix these)

2. Authentication and signature errors

3. Parameter and permission validation errors

4. User and enterprise errors

5. KYC, ticket and EDD errors

6. Card order and card configuration errors

7. Card management and card status errors

8. Hosted page errors

Declines under Partner-Managed (the important part)

Next steps