Error codes
General errors
| Error code | Description | Solution |
|---|---|---|
| 1000 | Internal Server Error. This error can be caused by several issues including expired Org Access Tokens. | Check your server configuration settings, including whether your Org Access Token has expired, and try again later. |
| 1003, 2003 | One or more required parameters are missing in the request. | The error_message field names the specific missing parameter. Identify that parameter, confirm which parameters are required in the API reference for the operation you are calling, add it, and retry. |
| 1006, 2006 | One or more parameters are in an invalid format or contain unsupported values. | The error_message field names the parameter that failed validation. Check the API reference for the operation you are calling to confirm the expected type, format, and allowed values for that parameter, then correct the value and retry. |
| 2000 | Internal error occurred during processing. | This is a temporary error on Coboâs side. Retry after a short delay. If the error persists, contact Cobo support at [email protected] and provide the error_id from the response so the failure can be traced. |
| 2021 | The requested API endpoint is not implemented or is currently unavailable. | Confirm the request path and HTTP method exactly match the operation in the API reference (a trailing slash or wrong method also returns this error). If they are correct, the endpoint may be temporarily unavailable â retry after a short delay using exponential backoff. |
| 2024 | API key authentication failed. |
|
| 2025, 4001 | Forbidden access to the requested resource. |
|
| 2026 | Too many requests. | Reduce your request frequency and retry after a short delay. For polling or batch patterns, implement exponential backoff â for example, start with a 1-second delay and double it on each retry (1s, 2s, 4s, âŚ) up to a maximum. |
| 2028 | The requested resource was not found. | The resource ID does not exist in your organization or was created in a different environment. List the relevant resources to confirm the correct ID (for example, call List transactions for a transaction_id), then retry with a valid ID. Confirm you are calling the same environment (Development or Production) in which the resource was created. |
| 2029 | The value provided for the status parameter is not one of the allowed values. | The allowed values for status depend on the operation (for example, transaction status differs from screening status). In the API reference, open the operation you are calling and provide one of the status enum values listed for its request parameters. |
| 10000 | This organization has read-only permissions in Cobo Portal. | Your organization currently has read-only access, so write operations are rejected. A team admin must log in to Cobo Portal and review the organizationâs access status in the organization settings; only a team admin can change the access level. Members without the admin role cannot change this setting. |
Pricing plan errors
| Error code | Description | Solution |
|---|---|---|
| 2050 | No pricing plan is active for this organization, so billable API operations are blocked. | Activate a pricing plan: log in to Cobo Portal, open Bills & Payments, and select a plan. For more information, see Introduction to Bills & Payments. |
| 2051 | The organizationâs pricing plan has expired, so billable operations are blocked until it is renewed. | Renew your pricing plan: in Cobo Portal, open Bills & Payments and renew or select a plan. For more information, see Introduction to Bills & Payments. |
| 2052 | The organization has exceeded the usage quota included in its current pricing plan. | Wait for the next billing cycle to reset the quota, or upgrade to a higher plan in Cobo Portal under Bills & Payments. For more information, see Introduction to Bills & Payments. |
| 2053 | The current pricing plan does not include the entitlement required for this operation. | Upgrade to a plan that includes this feature in Cobo Portal under Bills & Payments. For more information, see Introduction to Bills & Payments. |
| 2054 | Payment for the current pricing plan is overdue (the organization is in arrears), so the plan is suspended. | Settle the outstanding balance in Cobo Portal under Bills & Payments to restore service. For more information, see Introduction to Bills & Payments. |
Wallet configuration errors
| Error code | Description | Solution |
|---|---|---|
| 2101 | The wallet name exceeds the maximum allowed character length. | Wallet names can contain up to 100 characters. For Smart Contract Wallets, the maximum is 50 characters. The error_message reports the exact limit that applies to your request. Shorten the wallet name to that limit or fewer, then retry. |
| 2102 | The wallet name contains invalid characters. | The Cobo API rejects wallet names that contain any of the following characters: +, -, =, @. Remove these characters from the wallet name and retry. |
| 2103 | A wallet with this name already exists in the organization. | Wallet names must be unique within an organization. Choose a name that is not already used by another wallet and retry. To see names in use, list your existing wallets. |
| 2104 | The specified chain is not enabled for this organizationâs pricing plan. | To check which chains are already enabled, call the List enabled chains operation. If you need to enable or disable chains in Cobo Portal, see Enable or disable chains. Then retry with a chain that is enabled for your organization. |
| 2105 | For UTXO-based tokens (such as BTC), all available UTXOs are currently locked by a pending transaction or a transaction pending KYT screening. A new transfer cannot proceed until those UTXOs are released. | Call the List transactions operation, filtered to this wallet, to find the pending transactions that are holding the UTXOs. The UTXOs are released only when those transactions reach a terminal state (for example, completed or failed). Retry the transfer after the locking transactions reach a terminal state. |
Transfer errors
The following error codes are returned by transfer and withdrawal operations.| Error code | Description | Solution |
|---|---|---|
| 30000 | Unauthorized. You do not have permission to perform this transfer. | Check the permissions and wallet scopes associated with your API key. See Permissions and wallet scopes for details. |
| 30001, 12009 | The request_id has already been used. | Use a unique request_id for each new transaction. Duplicate request_id values are rejected to prevent duplicate transactions. |
| 30002 | The specified token is not supported for this operation or organization. | Verify the token_id is correct. Call the List supported tokens operation to get the full list of supported tokens. |
| 30003 | The wallet type does not support this transfer operation. | Verify that the wallet type is compatible with the requested transfer. |
| 30004 | The source wallet ID is invalid or the wallet does not exist. | Verify the from_wallet_id value is correct and the wallet belongs to your organization. |
| 30005 | The source address format is invalid or not compatible with the token. | Provide a valid source address that is compatible with the token type. |
| 30006 | The source address encoding format is not supported. | Use an address encoding format that is supported for this token. |
| 30007 | Invalid amount. The value is not a valid number or does not meet the required format or range. | Provide a positive numeric amount. Call the Get token information operation to retrieve the tokenâs decimal precision and ensure the amount does not exceed it. |
| 30008 | The abs_amount value must be greater than 0. | Provide a positive, non-zero value for abs_amount. |
| 30009 | The amount cannot be less than zero. | Provide a non-negative amount. |
| 30010 | The withdrawal amount is below the minimum threshold for this token and cannot be processed. | Increase the withdrawal amount. Call the Get token information operation to retrieve the dust_threshold value for this token. |
| 30011 | The deposit amount is below the minimum deposit threshold for this token. | Increase the deposit amount. Call the Get token information operation to retrieve the minimum_deposit_threshold value for this token. |
| 30012, 12007 | The transfer amount exceeds the walletâs available balance. | Check the walletâs available balance, which equals the total balance minus any pending and reserved amounts. Call the Get wallet balance operation to verify. |
| 30013 | The fee token balance is insufficient to cover the transaction fee. | Ensure the wallet or Fee Station has sufficient balance in the fee token (for example, ETH on EVM chains) to cover the transaction fee. |
| 30014 | The destination address is invalid or not compatible with the token. | Provide a valid destination address that is compatible with the token type. |
| 30015 | The destination wallet ID is invalid or the wallet does not exist. | Verify the to_wallet_id value is correct and the wallet belongs to your organization. |
| 30016 | The number of transaction categories exceeds the maximum of 5. | Reduce the number of categories in the category_names field to 5 or fewer. |
| 30017 | The category name exceeds the maximum of 30 characters. | Shorten the category name to 30 characters or fewer. |
| 30018 | The description exceeds the maximum of 100 characters. | Shorten the description field to 100 characters or fewer. |
| 30019 | The transfer was rejected by the on-chain transaction policy of a Smart Contract Wallet. | In Cobo Portal, go to Wallets > Smart Contract Wallets > the target wallet. In the On-Chain Transaction Policies section, review the policy in Current (and Queue if you have pending edits) to confirm whether the destination address, token, or method is blocked. Update the policy condition that blocks this transaction, submit the change, complete any required approval, and then retry. |
| 30020 | The token is not in the on-chain whitelist of your Smart Contract Wallet. | In Cobo Portal, go to Wallets > Smart Contract Wallets > the target wallet. In On-Chain Transaction Policies, edit the policy that governs token transfers and add the required token to the allowlist/condition used by that policy. Submit the policy change, complete any required approval, and retry the transfer. |
| 30021 | The destination address is not in the on-chain transfer whitelist of your Smart Contract Wallet. | In Cobo Portal, go to Wallets > Smart Contract Wallets > the target wallet. In On-Chain Transaction Policies, edit the policy that governs transfers and add the destination address to the allowed address condition. If the policy references an address list, first go to Wallets > Transaction Policies > Address Lists, add the address there, then return to the wallet policy, submit the change, complete approval, and retry. |
| 30022 | An invalid trading account type was specified as the transfer source for an Exchange Wallet. | Provide a valid trading account type as the transfer source. |
| 30023 | An invalid trading account type was specified as the transfer destination for an Exchange Wallet. | Provide a valid trading account type as the transfer destination. |
| 30024 | Neither to_wallet_id nor to_address was provided. | Provide either to_wallet_id or to_address as the transfer destination. |
| 30025 | Withdrawals are currently unavailable for this wallet or token. | In Cobo Portal, open the target wallet, locate the target token in the walletâs token or asset list, and check whether that token row provides a Withdraw action. If Withdraw is not available, that wallet/token combination does not support withdrawals. If the token is not shown in the list, add the token to the wallet first; if the add-token flow indicates that the tokenâs chain is not enabled, see Enable or disable chains. |
| 30026 | Transfers are currently unavailable for this wallet. | In Cobo Portal, open Wallets > the wallet type that matches this request > the target wallet, then verify from the wallet detail page that transfers are allowed for that wallet. If the wallet is restricted by wallet status, approval settings, or policy configuration, update the relevant setting before retrying. |
| 30027 | Deposits into the destination wallet are currently unavailable. | Confirm that the destination token has been added to the destination wallet and that the tokenâs chain is enabled for your organization. If you need to enable or disable chains in Cobo Portal, see Enable or disable chains. If that token or wallet still does not support deposits, choose a destination wallet that supports deposits. |
| 30028 | The request_id parameter is missing or invalid. | Provide a valid, non-empty request_id with the request. |
| 30029 | Trading account sub-wallets cannot initiate withdrawal transactions in an Exchange Wallet. | Use the Exchange Walletâs main account to initiate the withdrawal, not a trading account sub-wallet. |
| 30030 | The deposit or withdrawal operation cannot proceed because Cobo has temporarily suspended deposit or withdrawal processing for this token. The platform rejects the related operation until the suspension is lifted. | You cannot lift this suspension yourself; it is controlled on Coboâs side. To be notified when a token is suspended, subscribe to the token.suspended.deposit and token.suspended.withdraw events when you register a webhook endpoint, either on Cobo Portal (see Register a webhook endpoint, where you select the event types to subscribe to) or by calling the Register webhook endpoint operation (POST /webhooks/endpoints) with subscribed_events set to ["token.suspended.deposit", "token.suspended.withdraw"]. Then retry the operation after the suspension is lifted. |
| 30031 | The specified token has not been enabled for this organization. | Call the List enabled tokens operation to confirm the token is not yet enabled. Then add the token to the target wallet; if the flow indicates that the tokenâs chain is not yet enabled, see Enable or disable chains. Retry after the token is available in the wallet. |
| 30032 | No key share holder group is available for signing in this MPC Wallet. | In Cobo Portal, go to Wallets > MPC Wallets > the target vault > Key Share Management. Confirm that the vault has an available Main Group or Signing Group that can sign this transaction. If neither exists or the available group is unusable, create or recover the required group in Key Share Management first, then retry the transaction. |
| 30033 | The recipient address does not belong to Cobo, or Cobo Loop has been disabled for these wallets. | Verify that the recipient address is a Cobo address and that Cobo Loop is enabled for both wallets. To send to a non-Cobo address, use a standard withdrawal instead. |
| 30034 | The transaction was rejected by the on-chain transaction policy of a Smart Contract Wallet. | In Cobo Portal, go to Wallets > Smart Contract Wallets > the target wallet. In the On-Chain Transaction Policies section, inspect the policy in Current or Queue that matches this transaction type, then update the specific blocked rule, submit the policy change, complete any required approval, and retry the transaction. |
| 30035 | The Exchange Wallet is connected in Observation mode, which is read-only and does not support withdrawals. | Switch to an Exchange Wallet connected in Normal mode, or use a different wallet that has withdrawal permissions. |
| 30036 | The Fee Station balance is insufficient. Transactions cannot proceed until it is recharged. | In Cobo Portal, go to Fee Station. You can use the USD / USD Stablecoins tab to deposit supported USD stablecoins, or switch to the Gas Token tab to deposit the native gas token required by the target network. Retry after the balance is updated. |
| 30037 | The source and destination wallets are not eligible for Cobo Loop transactions. | Verify that both wallets support Cobo Loop. Use a standard transfer for wallets that are not Cobo Loop eligible. |
| 30038 | The Fee Station token balance is insufficient to cover the transaction fee. | In Cobo Portal, go to Fee Station > Gas Token and deposit the exact native gas token required by the network for this transaction. Retry after that token balance is sufficient. |
| 30039 | Coboâs Fee Station balance is insufficient to pay for gas. | This error is caused by a temporary condition on Coboâs side. Retry after a short delay. |
Token and balance errors
| Error code | Description | Solution |
|---|---|---|
| 12002 | The specified token is not supported by Cobo. | Choose a supported token. Call the List supported tokens operation to get the full list of supported tokens. |
| 12025 | The UTXOs specified in included_utxos or excluded_utxos are invalid. | Verify the UTXOs specified in included_utxos or excluded_utxos. |
| 60010 | The specified token has not been enabled for this organization. | Enable the token for your organization in Cobo Portal. Call the List enabled tokens operation to see all tokens currently enabled for your organization. |
| 60020 | The specified address is not enabled for the given token and wallet combination. | Verify that the address is associated with the correct wallet and token in your organization settings. |
Transaction management errors
| Error code | Description | Solution |
|---|---|---|
| 60001 | The specified organization was not found. | Verify that your API key belongs to the correct organization and that you are calling the correct environment. |
| 60002 | The transaction type is invalid. | Provide one of the supported transaction types: Transfer, ContractCall, or MessageSign. |
| 60003 | The transaction fee could not be estimated. | Retry the fee estimation after a short delay. If the error persists, verify that the token is supported and that the chain is enabled for your organization. If you need to review or change enabled chains in Cobo Portal, see Enable or disable chains. |
| 60004 | The transaction could not be found for the requested action. | Verify the transaction_id value and confirm that the transaction exists in your organization. |
| 60005 | The transaction cannot be canceled because it is in a state that does not allow cancellation. | Check the current transaction status. Only transactions in certain states (such as Pending) can be canceled. |
| 60006 | The transaction cannot be dropped. | The transaction is in a state that does not allow it to be dropped. Check the transaction status before retrying. |
| 60007 | The transaction cannot be sped up. | The transaction is in a state that does not allow a speed-up. This may occur when the transaction is already confirmed or in a terminal state. |
MPC wallet errors
| Error code | Description | Solution |
|---|---|---|
| 50000 | The MPC Vault does not have backed-up key shares for the Main Group. | In Cobo Portal, go to Wallets > MPC Wallets > the target vault > Key Share Management. Open the Main Group, check its backup status, and complete the pending key share backup for every holder. Retry this operation only after the Main Group shows as backed up. |
Smart contract and EVM errors
The following error codes are returned by smart contract wallet and EVM contract call operations. Note: Error codes 40001â40003 are also returned by transaction category operations with different meanings. Use the operation you called and theerror_message to determine which meaning applies.
| Error code | Description | Solution |
|---|---|---|
| 5001 | The contract ABI is invalid or cannot be parsed. | Verify that the ABI JSON is correctly formatted and complete. |
| 5002 | One or more parameters passed to the EVM operation are invalid. | Check the parameter types and values against the contract ABI definition. |
| 5003 | The transaction calldata is invalid or improperly encoded. | Verify that the calldata is correctly ABI-encoded for the target function. |
| 5004 | The requested EVM resource was not found. | Check the contract address and chain ID in the request. |
| 40001 | The external data source (such as a block explorer) rate limit has been reached. | Retry after a short delay. This is a temporary condition caused by upstream rate limits. |
| 40002 | The contract source code is not verified on the block explorer. | Verify the contract source code on the relevant block explorer (such as Etherscan) before attempting ABI-related operations. |
| 40003 | The specified chain is not supported for this EVM operation. | Use a supported chain. If you need to review which chains are enabled for your organization in Cobo Portal, see Enable or disable chains. |
MFA errors
The following error codes are returned when Cobo Guard multi-factor authentication (MFA) is required or fails.| Error code | Description | Solution |
|---|---|---|
| 40201 | The Cobo Guard key provided is invalid or has expired. | In Cobo Portal, click your avatar in the top-right corner, then go to Account > Security. In the Cobo Guard section, either click View Pubkey and TSS Node ID to confirm you are using the correct active key, or click Reset / Set Up to bind a new Cobo Guard key. After the active key is updated, retry the operation with that key. |
| 40202 | The Cobo Guard request is still pending and has not been completed. | Wait for the Guard request to be approved or rejected before proceeding. |
| 40203 | The Cobo Guard request has no approval or rejection result yet. | Check the status of the pending Guard request and complete it before retrying. |
| 40204 | The user performing this operation must be the same user who initiated the Guard request. | Ensure the same user account is used for both initiating and completing the Cobo Guard MFA request. |
Transaction category errors
The following error codes are returned by transaction category management operations. Note: Error codes 40001â40003 are also returned by EVM operations with different meanings. Use the operation you called and theerror_message to determine which meaning applies.
| Error code | Description | Solution |
|---|---|---|
| 40000 | The category name exceeds 30 characters. | Shorten the category name to 30 characters or fewer. |
| 40001 | The specified organization was not found. | Verify your organization ID and API key environment. |
| 40002 | The number of transaction categories has reached the maximum limit. | Delete unused categories before creating new ones. |
| 40003 | A category with this name already exists in the organization. | Use a unique category name. |
| 40004 | The category name contains invalid characters. | Use only allowed characters in the category name. |
Compliance and KYT errors
The following error codes are returned by compliance and Know Your Transaction (KYT) operations.| Error code | Description | Solution |
|---|---|---|
| 40101 | The compliance request for the specified transaction_id was not found. | Verify the transaction_id is correct and that a compliance check has been initiated for it. |
| 40102 | The compliance request cannot be retried because it is not in a failed state. | Check the current status of the compliance request before retrying. Only requests in a Failed state can be retried. |
| 40103 | This transaction does not support the requested operation (it is not an EOA/Web3 transaction, or it does not have an on-chain transaction ID). | Confirm that the request type you are submitting is supported by the compliance API. |
| 40104 | The KYT disposal type provided is invalid. | Provide a valid disposal type for the KYT operation. |
| 40105 | The specified KYT request was not found. | Verify the KYT request ID. |
| 40106 | A disposal request for this KYT screening already exists. | Check for an existing disposal request before creating a new one. |
| 40107 | A withdrawal request for this KYT disposal already exists. | Check for an existing withdrawal request before creating a new one. |
| 40108 | The status filter value provided when querying the KYT audit list is invalid. | Use a status value supported by that operation when querying the KYT audit list. |
| 40109 | No KYT screening request was found for the specified transaction_id. | Verify the transaction_id and ensure that a KYT screening was initiated for it. |
| 40110 | No KYT screening request was found for the specified screening_request_id. | Verify the screening_request_id value. |
| 40111 | The transactionâs current status does not allow a disposal action. | Check the transactionâs current status before initiating a disposal. |
| 40112 | The disposal parameters provided are invalid for this transaction. | Review the disposal parameters and ensure they are consistent with the transactionâs screening result. |
| 40113 | The KYT request is already being disposed of or has already been disposed of, so a new disposal action cannot be initiated. | Do not submit a duplicate disposal request for the same KYT request. Confirm the requestâs current disposal status first, then decide whether any further action is needed. |
| 40114 | The transactionâs current status does not allow an unfreeze action. | Check the transactionâs current status before attempting to unfreeze it. |
| 40115 | The disposal fee for the KYT request is invalid. | Provide both estimated_fee_type and estimated_fee_detail in the KYT disposal request. This error occurs when estimated_fee_type is empty, or when estimated_fee_detail is empty or cannot be parsed into a valid transaction fee object. Check the API reference for the disposal operation for the expected estimated_fee_detail structure, then retry. |
| 40116 | The disposal fee for the screening request is invalid. | Provide a non-empty estimate_transaction_fee value in the screening disposal request. This error occurs when that field is missing or empty. |
| 40117 | The fee payment method for the KYT disposal is invalid. | Set fee_payment_method to one of the allowed values: CUSTOMER_FEE_STATION, CUSTOMER_CURRENT_ADDRESS, or COBO_FEE_STATION. An empty or missing value is also rejected. |
| 40118 | The destination address for the KYT disposal is invalid. | The to_address must be either one of the original sender addresses of the screened transaction or a valid address on that transactionâs chain. Provide an address that meets one of these conditions and retry. |
| 40119 | An error occurred during the KYT disposal process. | Verify your request parameters are correct, then retry. If the error persists, go to Approvals > Initiated By Me or All Approvals in Cobo Portal, open the KYT disposal approval record for this request, and review its latest status and failure details before resubmitting. |
| 40120 | The disposal amount for the screening request is invalid. | Verify the disposal amount in the screening disposal request. |
| 40121 | The disposal amount for the KYT request is invalid. | Verify the disposal amount in the KYT disposal request. |
| 40122 | The wallet balance is insufficient to cover the estimated transaction fee for the disposal. | In Cobo Portal, open Wallets > the wallet type that holds the screened funds > the target wallet, and confirm that the wallet holds enough native gas token to pay the disposal fee. If your disposal uses Fee Station, also go to Fee Station and confirm the fee-paying token balance is sufficient there before retrying. |
| 40123 | A disposal action cannot be initiated because the transaction is not currently frozen. | A KYT disposal can only be applied to frozen transactions. Verify the transactionâs current status before proceeding. |
| 40124 | No compliance request was found for the specified transaction hash. | Verify the transaction hash. |
| 40125 | The app check request for the specified transaction_id was not found. | Verify the transaction_id and ensure that a compliance app check was initiated for it. |
| 40126 | The KYT screening completion result is invalid or malformed. | Review the result format returned by the KYT provider. |
Travel Rule errors
The following error codes are returned by Travel Rule compliance operations.| Error code | Description | Solution |
|---|---|---|
| 70001 | A general Travel Rule error occurred. | Check the error message for details and review your Travel Rule request parameters. |
| 70002 | The originator KYC information is invalid or incomplete. | Provide complete and valid KYC information for the originator. |
| 70003 | The Travel Rule vendor code is invalid. | Provide a valid vendor code. |
| 70004 | The originatorâs natural person entity information is missing or incomplete. | Complete all required natural person entity fields for the originator. |
| 70005 | The originatorâs legal entity information is missing or incomplete. | Complete all required legal entity fields for the originator. |
| 70006 | The originator information is missing or incomplete. | Provide all required originator information. |
| 70007 | An error occurred while entering the sender information. | Check the error message for details and verify the sender information fields. |
| 70008 | This Travel Rule operation is not supported for self-custody wallets. | Use a Cobo-managed wallet for this Travel Rule operation. |
| 70009 | Originator information has already been submitted for this record. | Originator information can only be submitted once per record. Review the existing record if updates are needed. |
| 70010 | The self-custody wallet signature verification failed. | Ensure the signature is generated correctly for the self-custody wallet address. |
| 70011 | The legal entity information is incomplete â required fields are missing. | Provide all required fields for the legal entity. |
| 70012 | The natural person entity information is incomplete â required fields are missing. | Provide all required fields for the natural person entity. |
| 70013 | This address has already been verified. | No further action is needed. Address verification is a one-time operation. |
HTTP status codes
| Status code | Description | Solution |
|---|---|---|
| 200 | OK. | N/A |
| 400 | Bad request. | Check the request parameters. |
| 401 | Unauthorized. | Check whether the API key matches the current environment (Dev/Prod), whether the API signature is correct, and whether the timestamp is valid and consistent with the fields used in signing. |
| 403 | Forbidden. |
|
| 404 | Not Found. | Check the requestURL. |
| 405 | Method Not Allowed. | Use a supported HTTP method. |
| 406 | Not Acceptable. | Ensure the request content format is JSON. |
| 429 | Too Many Requests. | Reduce request frequency and try again later. |
| 500 | Internal Server Error. This error can be caused by several issues including expired Org Access Tokens. | Check your server configuration settings, including whether your Org Access Token has expired, and try again later. |
| 502 | Bad Gateway. | Check the connectivity and try again later. |
| 503 | Service Unavailable. | Try again later. |