> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/developers/llms.txt
> Use this file to discover all available pages before exploring further.
# Error codes and status codes
> List of error codes for the WaaS 2.0 API, with explanations and troubleshooting tips.
Try [Cobo WaaS Skill](/v2/guides/overview/cobo-waas-skill) in your AI coding assistant (Claude Code, Cursor, etc.). Describe your needs in natural language to auto-generate production-ready SDK code and debug faster 🚀
This article explains the common error codes and HTTP status codes you may encounter when using the Cobo WaaS 2.0 API and how to resolve the errors.
### Error codes
| Error code | Description | Solution |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1000 | Internal Server Error. This error can be caused by several issues including expired [Org Access Tokens](/v2/apps/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. | Provide all required parameters. |
| 1006, 2006 | One or more parameters are in an invalid format or contain unsupported values. | Provide valid parameters in the expected format. |
| 12002 | The specified token is not supported by Cobo. | Choose a supported token. Call the [List supported tokens](/v2/api-references/wallets/list-supported-tokens) operation to get the full list of supported tokens. |
| 12007, 30012 | Insufficient balance to perform the requested operation. | Ensure the source address has sufficient balance to cover the transferred amount. |
| 12009, 30001 | Duplicate request ID. | Use a unique request ID. |
| 12025 | The UTXOs specified in `included_utxos` or `excluded_utxos` are invalid. | Verify the UTXOs specified in `included_utxos` or `excluded_utxos`. |
| 2000 | Internal error occurred during processing. | Please try again later. |
| 2021 | The request handler is missing or not implemented. | Provide a valid handler for the request. |
| 2024 | API key authentication failed. | - If `error_message` is `Your API key is not registered in this environment...`: you are using a key registered in the wrong environment. Switch to the correct API host and use the matching API key. See [Environments](/v2/guides/overview/environments).
- If `error_message` is `Your API key is not yet activated...` or `Api key is not activated`: complete Admin approval in Cobo Guard for the key to become Active.
- If `error_message` mentions the IP whitelist: add your server's egress IP to the key's allowlist in Cobo Portal.
- For signature failures, ensure the canonical string follows the format `METHOD\|PATH\|NONCE\|PARAMS\|BODY` with the nonce identical to the `Biz-Api-Nonce` header. See [Authentication](/v2/guides/overview/cobo-auth).
For details, see Register an API Key. |
| 2025, 4001 | Forbidden access to the requested resource. | - Check the permissions, wallet scopes, and resource scopes associated with your API key. You can refer to [Permissions and wallet scopes](/v2/guides/overview/permissions-and-scopes) for details.
- If the error is related to user roles (for example, creating withdrawals or initiating transactions), make sure the operator has the required role (for example, withdrawals typically require Spender or Admin).
- If the error message contains "Resource out of organization (4001)", it usually means the resource you are accessing (for example, `wallet_id`) belongs to a different organization than the API key.
- If you have granted permissions but still get forbidden, check whether you are mixing Dev/Prod API keys or calling the wrong environment domain.
- For Custodial Wallet operations, verify that the permission is granted at the correct (upper) scope level (some permissions must be enabled in the parent Custodial Wallet settings).
- If this operation requires an enabled capability (feature flag / allowlist), ensure it is enabled in the target environment.
- If this is chain/asset related (for example, adding a chain but still seeing forbidden), confirm the chain/capability is enabled in your pricing plan/configuration.
|
| 2026 | Too many requests. | Please try again later. |
| 2028 | The requested resource was not found. | Check the request URL. |
| 2029 | The provided status property is invalid. | Provide a valid value for the status property. |
| 2050, 2052 | No available pricing plan, or usage limit has been exceeded. | Purchase a pricing plan or upgrade your existing one. For more information, see [Introduction to Bills & Payments](https://manuals.cobo.com/en/portal/bills-and-payments/introduction). |
| 2051 | The current pricing plan has expired. | Renew your pricing plan to continue using the service. For more information, see [Introduction to Bills & Payments](https://manuals.cobo.com/en/portal/bills-and-payments/introduction). |
| 30007 | Invalid amount. The value is not a valid number or does not meet the required format or range. | Provide a valid amount that meets the expected format and range. |
| 30008 | Invalid absolute amount. The absolute value of the amount is either too small, too large, or zero when a non-zero value is required. | Ensure the absolute value of the amount meets the required conditions. |
| 30010 | The provided amount is below the dust threshold. It is too small to be processed or transferred. | Increase the amount to exceed the dust threshold. |
| 30011 | The provided amount is below the minimum deposit threshold. | Increase the deposit amount to meet the minimum threshold. |
| 30013 | Insufficient balance to cover the required transaction fee. | Ensure the source address has enough balance to cover transaction fees. |
| 30014 | The destination address is invalid. | Provide a valid destination address. |
| 30023 | (This error only applies to Exchange Wallets) Invalid trading account type. | Provide a valid trading account type. |
| 30032 | (This error only applies to MPC Wallets) Invalid key share holder group. | Check if a valid Main Group or Signing Group has been configured. |
| 60010 | The specified token has not been enabled for this organization. | Enable the token for your organization. |
### 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. | - Check the business error code in the response body first (for example, `2025`/`4001`) and troubleshoot permissions/roles/scopes/organization ownership accordingly.
- If you access the API via a reverse proxy/gateway, check gateway policies, egress public IP, WAF/firewall rules, and whether headers/paths are blocked or rewritten (for example, Cloudflare/Nginx).
- If the operation requires an enabled capability (feature flag / allowlist), ensure it is enabled in the target environment.
- If it is related to transaction risk controls (for example, auto-approval/policy blocks the operation), verify your risk control rules and policies allow the API operation.
|
| 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](/v2/apps/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. |