--- title: Error codes: COS Card payments slug: apis/payments/cos-card-payments/error-codes-cos-card-payments docTags: createdAt: 2025-12-16T06:34:47.771Z --- ## 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 ```json { "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/ | | **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 |