Error codes: COS Card payments

Overview

This page provides comprehensive error code information for the Card Payments API, including error codes, descriptions, and resolution guidance based on actual codebase analysis.

Error response format

Card payments API response format

{
  "error": {
    "code": "2001",
    "message": "Card expired",
  }
}

Error codes by category

Cards (2001-2006)

Errors related to card validation and authorization.

Code	Description	Resolution
2001	Card expired	Card expiration date has passed; use a valid card with future expiration date
2002	Card not found	Verify the card ID is correct; check if card exists in the system
2003	Card not authorized	Card is not authorized for this operation; verify card status and permissions
2004	Card capabilities not defined	Card capabilities must be defined in card configuration
2005	Card is inactive	Card must be in active status for this operation; activate card before processing payment
2006	Card account number does not match payment account number	Ensure card account number matches the payment account number

Payments (2101-2110)

Errors related to payment processing and validation.

Code	Description	Resolution
2101	Invalid payment status	Check current payment status; verify the requested operation is valid for the current status
2102	Payment not found	Verify the payment ID is correct; check if payment exists using GET /payments/id
2103	Preprocessing is required	Payment must be preprocessed before processing; call preprocessing endpoint first
2104	Payment information does not match preprocessing request	Payment data must match the preprocessing request; verify all fields match preprocessed data
2105	CVV is required for this payment	Include CVV (card verification value) in the payment request
2106	Payment cannot be finalized unless it's in a cleared status	Wait for payment to reach cleared status before attempting to finalize
2107	Valid OFAC scan could not be found	OFAC screening must be completed successfully before processing payment
2108	Payment source not valid for synchronous payments	Payment source type does not support synchronous processing; use asynchronous processing
2109	Domestic payments are not supported for preprocessing	Preprocessing is only available for international payments; process domestic payments directly
2110	Payment has OFAC hit	Payment has been flagged by OFAC screening; review and resolve OFAC compliance issue

Configuration (2200-2232)

Errors related to global, account, and product configuration management.

Code	Description	Resolution
2200	Global profile change not pending	Operation requires global profile change to be in pending status
2201	Global profile not found or is invalid	Verify global profile ID is correct and profile exists
2202	Global change not approved	Global configuration change must be approved before applying
2203	Global config change approval requires dual control	Have a second authorized user approve the global configuration change
2204	Global config required	Include global configuration object in the request
2205	Global config accounts must be unique	Use different account numbers for each global configuration field
2206	Offset account not found	Verify offset account exists; configure valid account number
2209	Account change not approved	Account configuration change must be approved before applying
2210	Account change not pending	Operation requires account change to be in pending status
2211	This action requires dual control	Have a second authorized user approve the configuration change
2212	Account has not been enabled to send credit transfers	Enable credit transfer send in account configuration
2213	Account config change approval requires dual control	Have a second authorized user approve the account configuration change
2214	Account configuration not found or is invalid	Verify account configuration ID is correct and configuration exists
2215	Product change not pending	Operation requires product change to be in pending status
2216	Product change not approved	Product configuration change must be approved before applying
2218	Product config change approval requires dual control	Have a second authorized user approve the product configuration change
2219	Account config required	Include account configuration object in the request
2220	Product config required	Include product configuration object in the request
2221	Product not configured	Product must be configured before processing payments
2222	Action not enabled for card brand	Card brand (Visa, Mastercard, etc.) does not support this action; verify card brand capabilities
2224	Daily total dollar amount limit exceeded	Daily payment amount limit reached; wait until next day or increase limit
2226	Daily sent payment count limit exceeded	Daily payment count limit reached; wait until next day or increase limit
2227	Payment type not allowed for this card	Card does not support this payment type; verify card capabilities and payment type
2228	Card issuer country not authorized for merchant	Card issuer country is not in merchant's authorized countries list; add country to whitelist
2229	Business type not allowed	Business type is not authorized for this merchant; verify merchant business type configuration
2230	CorrespondingEntity information is required	Include corresponding entity information in the request for regulatory compliance
2231	PurposeOfPayment is required for the card issuer country	Include purpose of payment for cross-border transactions from this card issuer country
2232	Full address is required for the card issuer country	Include complete address (street, city, state/province, postal code, country) for card issuer country compliance

Products (2301)

Errors related to product operations.

Code	Description	Resolution
2301	Product not found	Verify the product ID is correct and product exists in the system

FX rates (2401)

Errors related to foreign exchange rate operations.

Code	Description	Resolution
2401	Request failed	FX rate request failed; verify request parameters and retry

Holds (2500)

Errors related to payment hold management.

Code	Description	Resolution
2500	Hold is not active	Hold must be in active status for this operation; verify hold status

Security - payments (3001)

Security-related errors for payment operations.

Code	Description	Resolution
3001	Clearing hold exceeds user permissions for payment amount	Request approval from user with higher dollar limit for hold clearance

Security - configuration (3200)

Security-related errors for configuration operations.

Code	Description	Resolution
3200	Access denied	User lacks permission to access configuration; verify user has appropriate role and permissions