> ## 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.
# Authorization declines and error codes
> Decline reasons; where the general and authorization error codes live.
## 📄 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:
```json theme={null}
{
"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](../cards/card-order-codes)) and the KYC ticket's `data.errorCode` (see [KYC rejection codes](../kyc/kyc-reject-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](../../getting-started/first-steps).
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](../../basic-concepts/compliance-kyc-flow).
KYC rejection reasons are returned through the KYC ticket's `data.errorCode` / `errorMessage`; the full mapping is in [KYC reject codes](../kyc/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](../cards/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](./authorization); for where `rejectReason` sits in the report files, see [the authorization report](../reports/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](./transaction) to understand how Auth, Outstanding and Transaction relate, or go to [Sandbox simulation](../sandbox/simulating-transactions) to replay a declined authorization in the test environment.