---
title: Error codes: Cards
slug: apis/cards/error-codes-cards
description: Reference common error codes and their descriptions to troubleshoot issues in Cross River's card management APIs.
docTags:
createdAt: 2024-08-15T13:44:55.270Z
---
## Overview
This page provides comprehensive error code information for the Cards API, including error codes, descriptions, and resolution guidance based on actual codebase analysis.
## Error response format
```json
{
"error": {
"code": "2001",
"message": "{2001}CustomerId was not found or not associated with Card",
}
}
```
## Error codes by category
### General exception
| Code | Description | Resolution |
| -------- | ---------------- | ----------------------------------------------------------------------------------------- |
| **1000** | Validation error | General validation error; check request parameters and contact support if issue persists. |
### Cards (2001-2042)
Errors related to card operations, activation, suspension, and management.
| Code | Description | Resolution |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **2001** | CustomerId was not found or not associated with Card | Verify the customer ID is correct and has an active card association; check customer exists in the system |
| **2002** | Card can not be activated | Check card status and ensure card is in a state that allows activation; verify card has been issued and shipped |
| **2003** | Card was already activated | Card has already been activated; no further action needed unless card needs to be reissued |
| **2004** | Card can not be suspended | Verify card status allows suspension; ensure card is active before attempting to suspend |
| **2005** | Card is not suspended | Operation requires card to be in suspended status; verify card status before attempting operation |
| **2006** | Card is already closed | Card has been permanently closed and cannot be modified; issue a new card if needed |
| **2007** | PIN cannot be set on closed cards | Cannot set PIN on closed cards; issue a replacement card if PIN change is needed |
| **2008** | Account relationship type is not eligible for debit cards | Account type does not support debit card issuance; verify account type and relationship configuration |
| **2009** | Account does not belong to customer | Verify the account number is associated with the specified customer ID |
| **2010** | Card Order has not completed processing | Card order is still being processed; wait for order completion before attempting card operations |
| **2011** | Card is closed | Card is in closed status; operations cannot be performed on closed cards; issue a replacement card |
| **2012** | Request has not completed | Previous request is still processing; wait for completion before submitting new request |
| **2015** | Primary card not found | Primary card must exist before supplementary cards can be issued; create primary card first |
| **2020** | Card not found | Verify the card ID is correct; check if card exists using [Card details by ID](docId\:R5ZWm6VkWz-VS8_uVbZoH) |
| **2021** | Processor Card Id is invalid | Processor-assigned card ID is invalid or not found; verify card was successfully created at processor |
| **2022** | Customer already has a card for this account | Each customer can only have one card per account; use existing card or close it before creating new one |
| **2023** | Card Order must be complete | Operation requires card order to be in completed status; wait for order processing to finish |
| **2024** | Card has not been activated | Card must be activated before performing this operation; activate card first |
| **2025** | Card is already suspended | Card is already in suspended status; cannot suspend again |
| **2026** | Card is already AdminBlocked | Card is already blocked by administrator; cannot block again |
| **2027** | Card Configuration not found | Verify card configuration ID exists and is associated with the product |
| **2028** | Card Provider not found | Card provider configuration is missing; verify provider setup in system |
| **2029** | Card not found at processor | Card does not exist at the card processor; verify card was successfully created and synced |
| **2030** | Card order is not complete | Card order must complete before performing this operation; wait for order processing |
| **2031** | Company Name can only be used on cards associated with business accounts | Company name field requires business account classification; verify account type |
| **2032** | Card Replacement has not completed | Card replacement is still processing; wait for replacement to complete |
| **2033** | PIN must be four digits | PIN must be exactly 4 numeric digits; provide a valid 4-digit PIN |
| **2034** | Card has already been replaced | Card has been replaced with a newer card; operations should be performed on the replacement card |
| **2035** | Card can not be activated from current status | Check the current card status using [Card details by ID](docId\:R5ZWm6VkWz-VS8_uVbZoH) API endpoint; verify card is in a valid state for activation (e.g., not closed, not already activated); ensure card has been shipped before attempting activation |
| **2036** | Cannot close this card as newer card exists | A replacement card has been issued for this card; close the newer card first, or if the newer card should remain active, no action is needed on this older card |
| **2037** | Cannot authorize the card's account | Account authorization failed; verify the account is active and in good standing; check account has sufficient authorization to perform the requested operation; ensure account is not locked or restricted |
| **2038** | Authorization for the card's account timed out | Account authorization failed; verify the account is active and in good standing; check account has sufficient authorization to perform the requested operation; ensure account is not locked or restricted |
| **2039** | Wallet token not found | Digital wallet token does not exist; verify the token ID is correct; check token was successfully provisioned using the wallet provisioning API; ensure token has not been deleted |
| **2040** | Wallet token invalid status | Wallet token is not in a valid status for the requested operation; check token status using the [Retrieve specific wallet token](docId\:m4QVkVrG6emlcJBmOtz-7) API endpoint to verify token is active and not suspended or deleted |
| **2041** | Card token can only be suspended currently | Token status allows only suspension operations at this time; if you need to perform a different operation, first update token to a status that supports it; for deletion, suspend the token first |
| **2042** | Card token action is required. | A required action must be performed on the card token; check token lifecycle requirements; complete any pending activation or verification steps before proceeding |
### Card configuration (2100-2114)
Errors related to card configuration and product settings.
| Code | Description | Resolution |
| -------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **2100** | Cards Not Enabled On Product | Enable card issuance on the product configuration before attempting to create cards |
| **2101** | Card Config Not Found | Verify the card configuration ID is correct and exists in the system |
| **2102** | Card Config Change Not Pending | Operation requires a pending configuration change; verify change status |
| **2103** | Card Config Not Associated With Product | Associate the card configuration with the product before using it |
| **2104** | Card Config Not Enabled | Enable the card configuration before attempting to use it for card issuance |
| **2105** | ShippingType not supported by card configuration | Use a shipping type that is supported by this card configuration |
| **2106** | CardConfigStatus must be provided on updates | Include CardConfigStatus field when updating card configuration |
| **2107** | OffsetAccountNumber not found | Offset account number specified in configuration does not exist; verify the offset account number is correct; ensure offset account has been created in the system before configuring |
| **2108** | Card Processor cannot be changed | Card processor is immutable once set; to use a different processor, create a new card configuration; existing cards will continue using the original processor |
| **2109** | Card Config Program Id Not Found | Program ID referenced in card configuration does not exist; verify the program ID is correct; ensure program has been created before associating with card configuration |
| **2110** | Card Config Authorization Type cannot be changed | Authorization type is immutable once card configuration is created; to use a different authorization type, create a new card configuration; existing cards will use the original authorization type |
| **2111** | CardDesignId is not supported by card configuration | The specified card design ID is not compatible with this card configuration; verify card design ID is correct; check card design is enabled for this configuration |
| **2112** | Multiple Card Config Found | Query returned multiple card configurations when only one was expected; provide more specific search criteria such as exact configuration ID; verify configuration is not duplicated in the system |
| **2113** | Setting Program Id is already associated with a Partner | This program ID is already linked to another partner; each program ID can only be associated with one partner; use a different program ID or unlink from the existing partner first |
| **2114** | Setting CardDesign Id is already associated with a Partner | This card design ID is already linked to another partner; each card design can only be associated with one partner; use a different card design ID or unlink from the existing partner first |
### Product configuration (2150-2154)
Errors related to product configuration changes and approvals.
| Code | Description | Resolution |
| -------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **2150** | Change not approved | Configuration change must be approved before applying; submit for approval first |
| **2151** | Product change not pending | Operation requires product change to be in pending status; verify change status |
| **2152** | Product config change approval requires dual control | Have a second authorized user approve the product configuration change |
| **2153** | Product config required | Include product configuration object in the request |
| **2154** | Product Config Not Found | Product configuration does not exist; verify product configuration ID is correct; check product is active |
### Integration (2200)
Errors related to external system integrations.
| Code | Description | Resolution |
| -------- | ----------- | ------------------------------------------------------------------------------------- |
| **2200** | TCP Error | Network communication error with card processor; check network connectivity and retry |
### Accounts (2301-2302)
Errors related to account operations and status.
| Code | Description | Resolution |
| -------- | ----------------- | ------------------------------------------------------------------------------ |
| **2301** | Account not found | Verify the account number is correct and the account exists in the system |
| **2302** | Account is closed | Account is in closed status; operations cannot be performed on closed accounts |
### Simulator (2350-2364)
Errors related to transaction simulation and testing.
| Code | Description | Resolution |
| -------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **2350** | Authorization already been cleared | Authorization has been cleared; cannot perform operation on cleared authorization |
| **2351** | Auth was not found | Verify the authorization ID is correct; check if authorization exists |
| **2352** | Error occurred generating referenceid | System error generating reference ID; retry the operation |
| **2353** | Transaction was not found | Verify the transaction ID is correct; check if transaction exists |
| **2354** | Transaction has already been reversed | Transaction has been reversed; cannot reverse again |
| **2355** | Transaction Category is not valid | Provide a valid transaction category from the allowed list |
| **2356** | Transaction Type is not valid with this Category | Transaction type does not match the specified category; verify type/category combination |
| **2357** | Authorization was reversed | Authorization has been reversed; cannot perform operations on reversed authorization |
| **2358** | Auth was not found (duplicate of 2351, but for captures) | Authorization not found for capture operation; verify authorization ID is correct; ensure authorization exists and has not expired; check authorization was successful before attempting capture |
| **2359** | Host timeout already received for this transaction | A host timeout has already been recorded for this transaction; do not retry; transaction is in terminal state; query transaction status to determine final outcome |
| **2360** | Reversal amount cannot be more than the transaction amount | Reversal amount exceeds original transaction amount; verify reversal amount is correct; reversal amount must be less than or equal to the original transaction amount |
| **2361** | Action requires card has been previously activated | This operation requires the card to be activated; activate the card first using [Activate card by ID](docId\:E_U42earZiwDZOiIXuunI) API endpoint; verify activation completed successfully before retrying operation |
| **2362** | Action requires card has not been previously activated | This operation cannot be performed on an activated card; verify card status; if card should not have been activated, issue a replacement card |
| **2363** | Either retrieval reference number or system trace audit number must be present | Include either `retrievalReferenceNumber`
or `systemTraceAuditNumber` in the request; at least one identifier is required to process the transaction |
| **2364** | Either retrieval reference number or transaction identifier must be present | Include either `retrievalReferenceNumber`
or `transactionId` in the request; at least one identifier is required to locate the transaction |
### Bin sponsorship (2375-2380)
Errors related to BIN sponsorship card operations.
| Code | Description | Resolution |
| -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **2375** | PrimaryCustomerId was not found | Verify the primary customer ID is correct and customer exists in the system |
| **2376** | ParentCustomerId was not found | Verify the parent customer ID is correct and customer exists in the system |
| **2377** | Bin Sponsorship Card Already Exists | BIN sponsorship card already exists for this customer; use existing card or close it first |
| **2378** | Primary Customer and Parent Customer Must Have The Same PartnerId | Ensure both primary and parent customers are associated with the same partner |
| **2380** | Bin Sponsorship Card was not found | Verify the BIN sponsorship card ID is correct; check if card exists |
### Partners (2400-2401)
Partner management and validation errors
| Code | Description | Resolution |
| -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **2400** | Partner not found | Partner ID does not exist in the system; verify partner ID is correct; ensure partner has been onboarded; check partner has not been deleted; use GET /partners to list available partners |
| **2401** | Partner is inactive | Partner account is in inactive status; operations cannot be performed for inactive partners; contact partner administrator to activate partner account; verify partner agreement is current |
### COS card management (2450-2457)
| Code | Description | Resolution |
| -------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **2450** | LoanId is null or empty, cannot resolve account number | LoanId is required but was not provided or is empty; include valid LoanId in the request |
| **2451** | Failed to retrieve webhook secret from AWS Secrets Manager | Unable to access webhook secret from AWS Secrets Manager; verify AWS credentials are configured correctly; check Secrets Manager permissions; ensure secret exists in the correct AWS region; verify network connectivity to AWS |
| **2452** | Webhook secret key not found in AWS Secrets Manager | Webhook secret does not exist in AWS Secrets Manager; verify secret name is correct; ensure secret has been created in Secrets Manager; check secret is in the correct AWS region and account |
| **2453** | Unknown monetary event type | Webhook contains an unrecognized monetary event type; verify event type is supported; API documentation for valid event types; ensure webhook payload format matches expected schema |
| **2454** | No account configuration found for LoanId | LoanId does not have an associated account configuration; create account configuration for this LoanId |
| **2455** | Webhook payload is missing | Webhook request body is empty or null; ensure webhook payload is included in POST request body; verify Content-Type header is set to application/json; check webhook is configured correctly |
| **2456** | Webhook payload is missing event\_id | Required field `event_id` is missing from webhook payload; verify webhook payload includes `event_id` field; check webhook configuration; ensure webhook format matches expected schema |
| **2457** | Webhook payload is missing event\_type | Required field `event_id` is missing from webhook payload; verify webhook payload includes `event_id `field; check webhook configuration; ensure webhook format matches expected schema |
### Security - configuration (3001)
Security-related errors for configuration operations.
| Code | Description | Resolution |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| **3000** | General exception | |
| **3001** | Access denied | User lacks permission to access configuration; verify user has appropriate role and permissions |
### Security - cards (3100)
Security-related errors for card operations.
| Code | Description | Resolution |
| -------- | ----------------------- | --------------------------------------------------------------------------- |
| **3100** | Card is locked by admin | Card has been locked by administrator; contact administrator to unlock card |