Error code dictionary - DCS Technical Documentation

📄 Guide

This page is the complete set of error codes for the Corporate Card open API: 11 general codes and 52 business codes. Use it as a quick reference — the trigger conditions and request details for each code live in the guide pages named in the “Returned by” column. Three rules for handling errors:

Branch on the error code, never parse message: message is for humans and its wording will change; the code is the contract.
Never judge success by HTTP status: business failures currently return HTTP 500 across the board. The only reliable test is code == "SYS_SUCCESS".
SYS_ERROR and DAPI_SERVICE_UNAVAILABLE mean the outcome is unknown: for money-moving calls (transfers, card applications) retry with the same idempotency key or reconcile by query — do not treat them as failures outright. If you meet a code not listed here, treat that call as failed; never treat it as success.

Batch endpoints (rule bind / unbind) report errors on two levels: batch-level errors in the top-level code, and per-item failure reasons in data.failTargets[].errorCode, drawn from the same code set. See Binding and unbinding.

General error codes

Independent of any specific endpoint; any call may return them. The body is the standard envelope { code, message, data }.

Response envelope

Code	HTTP	Description
`SYS_SUCCESS`	200	Success
`SYS_ERROR`	500	System error (outcome unknown — retry money-moving calls with the same idempotency key)

Authentication and gateway checks

Code	HTTP	Description
`DAPI_API_KEY_EMPTY`	401	API key missing or invalid
`DAPI_TIMESTAMP_EXPIRED`	401	Timestamp outside the window
`DAPI_NONCE_ILLEGAL`	401	Illegal nonce
`DAPI_NONCE_DUPLICATE`	401	Duplicate nonce
`DAPI_SIGNATURE_ERROR`	401	Signature verification failed
`DAPI_IP_NOT_ALLOWED`	401	IP not on the allowlist
`DAPI_PERMISSION_DENIED`	401	Access denied
`DAPI_PARAM_INVALID`	400	Invalid parameters (including structural gaps such as “none of the five control groups configured”)
`DAPI_SERVICE_UNAVAILABLE`	500	Downstream unavailable (outcome unknown — handle like `SYS_ERROR`)

Business error codes

Code	Description	Returned by
`APPLY_DUPLICATE`	Duplicate application (idempotency key already exists)	Company application, employee application, card application, virtual-to-physical
`APPLY_REJECTED_USE_RESUBMIT`	Application was rejected; use the resubmit endpoint instead	Company application, employee application
`COMPANY_REGISTRATION_DUPLICATE`	Company registration number already exists	Company application
`CURRENCY_NOT_ALLOWED`	Currency not on the allowed list	Company application, opening a VA
`EMAIL_DUPLICATE`	Email already exists	Company application, employee application
`APPLY_NOT_FOUND`	Application not found	Application query and resubmit (company, employee), card application query
`STATUS_CONFLICT`	Status conflict	Resubmit and restriction updates (company, employee)
`COMPANY_INVALID`	Company missing, not ACTIVE, or not owned by this partner	Most endpoints under a company
`COUNTRY_SANCTIONED`	Sanctioned country	Employee application, employee address update, virtual-to-physical
`PHONE_DUPLICATE`	Phone number already exists	Employee application
`CUSTOMER_INVALID`	Employee missing, not ACTIVE, or not under the given company	Employee query, the four update endpoints, restrictions
`KYC_IN_REVIEW`	KYC under review; updates temporarily blocked	Employee information updates
`CARD_LIMIT_EXCEEDED`	Card count limit exceeded	Card application
`CARD_PROFILE_INVALID`	Card profile unavailable	Card application
`CARD_RULE_REQUIRED`	A velocity rule is required for this card profile	Card application
`CARD_RULE_INVALID`	Rule missing, not owned by this company, or not ACTIVE (one code for all three, to prevent probing other companies’ rules)	Card application
`CARD_RULE_DUPLICATE`	The subject is already bound to this rule	Card application, rule binding
`CARD_RULE_CURRENCY_NOT_MATCH`	No overlap between the rule’s currencies and the card’s chargeable currencies	Card application, rule binding
`CARD_RULE_LIMIT_EXCEEDED`	The subject already has the maximum number of rules (5)	Card application, rule binding
`SUBJECT_INVALID`	Subject missing, not ACTIVE, or not under the given company	Subject checks in the funds and velocity domains (including per-item results of batch calls)
`CARD_INVALID`	Card invalid	Most card-domain endpoints
`CARD_NOT_DEDICATED`	Not a dedicated-balance card	Opening a VA
`PCI_NOT_CERTIFIED`	No sensitive-card-data entitlement	Retrieving sensitive card data
`CARD_CONVERT_IN_PROGRESS`	A virtual-to-physical conversion is already in flight	Virtual-to-physical
`CARD_NOT_VIRTUAL`	Not a virtual card	Virtual-to-physical
`LIMIT_PHYSICAL_EXCEEDED`	Physical card limit exceeded	Virtual-to-physical
`SHIPPING_ADDRESS_REQUIRED`	Shipping address missing	Virtual-to-physical
`SHIPPING_CONTACT_REQUIRED`	Shipping contact phone missing	Virtual-to-physical
`SHIPPING_ADDRESS_INVALID`	Shipping address invalid or not usable for this card (batch shipping only)	Virtual-to-physical
`CARD_NOT_SHIPPED`	Card not yet shipped	Physical card activation
`CARD_NOT_ACTIVATED`	Card not activated	Set PIN
`CARD_STATE_INVALID`	The card state does not allow this operation	Most card and funds APIs
`PIN_DECRYPT_FAILED`	PIN ciphertext could not be decrypted	Set PIN
`PIN_RULE_VIOLATION`	PIN violates the PIN rules	Set PIN
`PIN_VERIFY_FAILED`	Identity verification factors do not match	Set PIN
`CURRENCY_MISMATCH`	The two sides of the transfer use different currencies	Funds transfer
`INSUFFICIENT_FUNDS`	Insufficient balance	Funds transfer
`SUBJECT_RESTRICTED`	Subject restricted (frozen / restricted state)	Funds transfer
`TRANSFER_DUPLICATE`	Duplicate transfer (idempotency key already exists)	Funds transfer
`TRANSFER_NOT_FOUND`	Transfer not found	Transfer query
`BALANCE_ALERT_CURRENCY_NO_POOL`	No funding pool opened for this currency	Balance alert settings
`VA_ALREADY_ACTIVE`	A VA for this subject and currency is already active	Opening a VA
`VA_REQUEST_PENDING`	The subject has an unfinished VA request in flight	Opening a VA, updating VA profile
`VA_PROFILE_NOT_FOUND`	The company has not submitted a VA profile (needed only in custom payee-name mode)	Opening a VA, updating VA profile
`VA_PROFILE_NOT_CHANGED`	The submission matches the existing profile; no new version produced	Updating VA profile
`VA_NOT_FOUND`	VA missing, not owned by the company, or not ACTIVE	Updating a VA, querying VA status
`VA_NOT_NAMED`	The VA uses the platform default payee name; there is no custom name to update	Updating VA profile
`VELOCITY_CURRENCY_INVALID`	Currency in an amount-limit group invalid or duplicated	Create / update velocity rule
`VELOCITY_LIMIT_VALUE_INVALID`	Limit value invalid (negative, malformed, over precision, or a longer period smaller than a shorter one)	Create / update velocity rule
`VELOCITY_LIST_CONTROL_INVALID`	List control group invalid (bad `filterType`, empty list, malformed entries)	Create / update velocity rule
`VELOCITY_BATCH_SIZE_EXCEEDED`	More than 200 items in one batch	Rule bind / unbind
`VELOCITY_LAST_PROTECTING_RULE`	The last active rule on a company-pool card cannot be unbound (per-item)	Rule unbind
`VELOCITY_RULE_CONTENT_EMPTY`	No control group configured	Create / update rule
`VELOCITY_RULE_INACTIVE`	The rule is not ACTIVE and cannot be bound (per-item)	Rule bind
`VELOCITY_LIST_CONTROL_EMPTY`	The list control group has an empty list	Create / update rule
`VELOCITY_TARGET_TYPE_INVALID`	Invalid subject type	Rule bind / unbind
`CARD_ALREADY_ACTIVATED`	The physical card has already been activated	Hosted-page link
`CARD_CUSTODIAN_INVALID`	Custodian missing or unusable	Card application, hosted-page link
`VELOCITY_RULE_NOT_FOUND`	Rule missing, or not owned by the given company / this partner	Rule query, update, status change, bind, unbind, bound-target query
`VELOCITY_RULE_STATUS_INVALID`	Rule status does not allow the operation	Rule update, status change, bind
`VELOCITY_RULE_VERSION_CONFLICT`	`ruleVersion` does not match the server (concurrent modification) — re-query and retry	Rule update, status change
`CARD_3DS_CHALLENGE_NOT_FOUND`	Challenge not found	3DS challenge confirmation

Next steps

The two-level error structure of batch bind / unbind and per-item failure handling: Binding and unbinding
Signature headers and where the DAPI_* codes come from: First steps
Resubmitting after a rejection: Company onboarding and Employee onboarding

​📄 Guide

​General error codes

​Response envelope

​Authentication and gateway checks

​Business error codes

​Next steps

📄 Guide

General error codes

Response envelope

Authentication and gateway checks

Business error codes

Next steps