> For the complete documentation index, see [llms.txt](https://docs.catfee.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catfee.io/en/getting-started/buy-energy-via-api-on-catfee/api-error-codes.md). # API Error Codes and Handling CatFee API error codes, meanings, compatibility notes, and retry guidance This page explains CatFee API business error codes and how to handle them. Check the HTTP response, business `code`, and order status when processing a result. {% hint style="info" %} Codes are listed in ascending numerical order. The business category indicates their scope; refer to the relevant endpoint documentation for applicability. Entries marked “legacy” are included for compatibility with existing integrations. {% endhint %} ## How to Determine the Request Result CatFee API business errors typically return **HTTP 200 with a nonzero integer `code`**. HTTP 200 alone does not indicate business success, and business code `201` is not HTTP status 201. Example error response: ```json { "code": 201, "msg": "Insufficient balance", "data": null } ``` | Field | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | Integer business code. `0` indicates a successful API call. Treat every nonzero code, including an unrecognized code, as a failure. | | `msg` | Error message. Wording may vary by situation or version. Branch on `code`, rather than matching message text. | | `data` | Data returned on success. It may be `null` or omitted on failure; do not process it as a successful result. | | `sub_code`, `sub_msg` | Optional additional information. The energy API uses these snake\_case names, rather than `subCode` and `subMsg`. They do not replace the main `code`. | Clients must also handle non-200 responses, network timeouts, empty responses, and non-JSON bodies. None of these should be treated as business success. Retain the HTTP status for troubleshooting even if the error body cannot be parsed. **A successful API call and a successful order are separate results.** Querying a failed order can still return `code=0`. Creating an order or receiving an existing order through an idempotent request does not mean the energy has arrived. Continue checking `data.status` and `data.confirm_status`; see [Buy Energy](/en/api-reference/create-order.md) and [Order Details](/en/api-reference/order-detail.md). ## Error Code Reference | code | Business category | Meaning and common causes | Recommended action | | ------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | General | Successful call, including returning an existing idempotent result | Process the returned data. For orders, continue checking the order status. | | `1` | General | Missing, malformed, or out-of-range parameters; some endpoints also use this code for invalid authentication details | Check parameters, authentication headers, signature, timestamp, and IP whitelist. Correct the request before resubmitting. | | `2` | Account and authentication | Authentication or access denied (legacy) | Check authentication details and permissions. Do not assume the login session has expired based on this code alone. | | `3` | General | Specified resource not found (legacy) | Check the resource ID, account, and environment. | | `4` | General | Request processing failed (legacy) | Check the original operation's result. Do not immediately resubmit an order or payment. | | `5` | General | Operation not allowed in the current state, or an invalid response (legacy) | Review the message and check the operation's status. Contact support if the result remains unclear. | | `100` | Account and authentication | Required credentials are missing | Supply the API authentication headers or sign in as required by the endpoint. | | `101` | Account and authentication | Credentials are invalid or expired, or signature verification failed | Check the Key, Secret, environment, and signature. Sign in again if the login session has expired. | | `102` | Account and authentication | Insufficient permission to access or modify the resource | Check resource ownership and permissions. Do not automatically sign the user out. | | `103` | Account and authentication | Second-factor verification is required for the sensitive operation | Provide the second-factor verification code required by the endpoint. | | `104` | Account and authentication | Second-factor verification failed | Check the verification code and settings. Avoid repeated invalid attempts; do not automatically sign the user out. | | `105` | Account and authentication | Second-factor verification is temporarily unavailable | Try verification again later. | | `106` | General | Request or verification attempt limit exceeded | Reduce the request rate and wait for the restriction to expire. Follow `Retry-After` if provided. Rate limits may also be returned as HTTP 429. | | `107` | Account and authentication | The request's source IP is not allowed | Check the actual outbound IP address and API IP whitelist. | | `108` | Account and authentication | The signature timestamp is outside ±30 seconds of the server's current time | Synchronize your server clock and generate a new UTC timestamp and signature. | | `109` | Account and authentication | The required second-factor authentication has not been configured | Enable second-factor authentication as required by the account. | | `110` | General | The current business state does not allow the operation; older endpoints or cases without a specific code may also use this for inactive addresses or quantities that do not meet current conditions | Check the current state, adjust the request, or wait until the conditions are met. Avoid immediately repeating the same request. | | `111` | General | Service response error; a valid result is temporarily unavailable | Read-only requests may be retried after a delay. Check the original operation before retrying an order or payment. | | `112` | General | The specified order, address, payment record, endpoint, hostname, plan, or node does not exist | Check the ID, account, and environment. Do not treat this as a successful empty list. | | `113` | General | Service temporarily unavailable, or no quote is available | Read-only requests may be retried with backoff. For orders, check the original result before following the endpoint's idempotency rules. | | `114` | General | The final outcome of the operation cannot currently be confirmed | **Check the original order and payment records first. For broadcasts, check the on-chain outcome using the original transaction hash. Do not immediately repeat the payment, order, or broadcast.** | | `115` | Account and authentication | An email or other verification code is invalid or expired | Obtain and enter a valid code. This does not indicate that the current login session has expired. | | `116` | Account and authentication | The temporary authentication flow is no longer valid | Restart the authentication flow. Do not repeatedly submit expired credentials. | | `201` | Payments and balance | Insufficient balance to cover the required fees | Add funds and check the original order. Follow the endpoint's idempotency rules when retrying the same purchase. | | `202` | Account and authentication | Account disabled | Stop retrying and contact support. | | `203` | Payments and balance | A payment or balance change conflicts with an existing record | Check payment records and the order. Do not pay again using a new ID. A successful idempotent request should return `0`. | | `999` | General | System error (legacy) | Retain troubleshooting details and confirm the original operation's result. Contact support if the problem persists. | | `1003` | Time-based rental | The energy receiver’s staking state and requested quantity do not meet rental limits | Check the receiver’s staking state and purchase quantity. Use an eligible address or adjust the quantity; contact support if the requirements still cannot be met. | | `1004` | Time-based rental | The receiver is not activated and the request does not allow automatic activation | Activate the receiver first, or allow automatic activation as supported by the endpoint and confirm the activation fee. | | `1005` | Time-based rental | Rental pricing is missing for the requested resource or price provider | Check the resource type and pricing configuration. Ask the relevant reseller or platform to configure the price, then request a new quote. | | `1006` | Time-based rental | The actual order amount, including activation fees, exceeds the confirmed amount limit | Request a new quote and confirm the total including activation fees. Check the original batch or order result before submitting according to the endpoint’s rules. | | `1101` | TRON Mate | The address is already bound to a hosting service, including Basic, Pro, or Flash | Look up and use or update the existing hosting configuration. Resolve the existing binding before switching services. | | `1102` | TRON Mate | The hosting address has not been activated on the TRON network | Activate the address and confirm its on-chain status before adding it to hosting. | | `1103` | TRON Mate | The address’s energy staking state does not meet the limits of the selected hosting mode | Check the hosting mode and the address’s staking state. Use an eligible address or contact support. | | `1104` | TRON Mate | The address has insufficient self energy to activate the selected Pro hosting mode | Check the address’s resources and configured quantity. Meet the selected mode’s energy requirements before activation; this is not an account balance error. | | `1105` | TRON Mate | The next subscription billing time has not been reached | Wait until the next billing time rather than repeatedly triggering billing early. | | `1201` | Seamless Energy | The proxy endpoint is disabled | Check the endpoint status and have an authorized account enable it before requesting again. | | `1202` | Seamless Energy | The broadcast transaction’s owner address is not bound to the endpoint | Check the transaction owner and endpoint. Bind the address to the correct endpoint before submitting again. | | `1203` | Seamless Energy | The bound address is disabled | Check the binding and have an authorized account enable the address. | | `1204` | Seamless Energy | The bound address has expired | Update the binding’s expiration time and confirm it is effective before requesting again. | | `1205` | Seamless Energy | The bound address has insufficient available quota | Check the quota mode, used quota, and reserved quota. Add quota as supported by the current mode; funding the account does not automatically increase address quota. | | `1206` | Seamless Energy | The quota mode or configuration changed during processing, preventing quota reservation | Refresh the binding configuration and check the original request’s outcome before proceeding with the current configuration. | | `1207` | Seamless Energy | The quota mode only supports USDT transactions recognized by the platform | Check the transaction type, USDT contract, and network. Use a transaction supported by the current quota mode. | | `1208` | Seamless Energy | The transaction’s energy requirement exceeds the per-transaction limit for the quota mode | Check the energy requirement and mode limits. Use a configuration that supports the requirement; adding total quota does not remove the per-transaction limit. | | `1209` | Seamless Energy | The energy estimate or purchase quantity is outside the allowed range | Check the transaction and its energy requirement. Contact support if the issue persists rather than repeatedly broadcasting the unchanged transaction. | | `1210` | Seamless Energy | Transactions are still being processed for the bound address, preventing the configuration change | Wait for in-flight transactions to finish, then refresh the binding before changing its configuration. | | `1211` | Seamless Energy | The custom hostname is already in use | Check existing hostname bindings and use an available hostname you are authorized to manage. | | `1212` | Seamless Energy | The endpoint limit has been reached | Review existing endpoints or contact support instead of repeatedly attempting to create another endpoint. | | `1213` | Seamless Energy | The endpoint is not in address-bound mode, so the address management operation is unavailable | Check the target endpoint and configure ADDRESS\_BOUND mode as needed before performing the operation. | | `1214` | Seamless Energy | The original transaction has expired | Check the on-chain outcome using the original transaction hash. If a new transaction is needed, rebuild and sign it; do not keep broadcasting the expired transaction. | | `1215` | Seamless Energy | Quota increments are unavailable in unlimited quota mode | UNLIMITED mode does not require quota increments. Check the current quota mode and the endpoint being called. | | `1301` | Energy reselling | The actual energy receiver’s staking state and requested quantity do not meet reselling limits | Check the actual receiver, including an address specified in the transfer memo, and the quantity. Adjust them according to the service rules; do not immediately repeat the transfer. | | `1302` | Energy reselling | The configured reselling payment address has not been activated | Activate the payment address and confirm its on-chain status before saving the reselling configuration. | | `1303` | Energy reselling | The reselling payment address already exists and cannot be configured again | Check the existing configuration. Only update a configuration you are authorized to manage, or use another eligible payment address. | | `1304` | Energy reselling | The member has reached the limit on configured reselling addresses | Review existing address configurations or contact support instead of repeatedly attempting to add an address. | | `1401` | Flash | The Flash receiver or hosting address has not been activated on the TRON network | Activate the address and confirm its on-chain status before requesting Flash service. | | `1402` | Flash | The address still has unfinished resource orders | Check and wait for the existing orders to complete before making a new request. Avoid duplicate orders. | | `1403` | Flash | The address’s base resources do not meet Auto Flash requirements for the configured threshold, refill amount, or delegation limits; applies to energy and bandwidth | Check the address’s base resources, trigger threshold, and refill amount. Adjust them to meet the requirements before resubmitting; adding funds to the account alone does not resolve this error. | | `1404` | Flash | The address is already bound to a hosting service such as Flash, Basic, or Pro | Check the existing hosting configuration. Resolve the existing binding before switching services. | | `1801` | Node | A subscription change is already pending | Check and resolve the existing subscription change before creating another change order. | | `1802` | Node | The target plan increases some price, quota, or rate metrics and decreases others, making the change direction ambiguous | Choose a plan with a consistent upgrade or downgrade direction, or contact support. | | `1803` | Node | The target plan has the same price, quota, and rate as the current plan | Keep the current plan or choose one with different metrics instead of resubmitting the same change. | | `1804` | Node | Creating or accessing a node requires an active subscription; the subscription record may be missing during access | Check the subscription and order status. Complete the subscription and confirm it is active before proceeding. | | `1805` | Node | The node is paused | Check the node status and have an authorized account resume it before requesting again. | | `1806` | Node | The node subscription has expired | Renew the subscription and confirm it is active before requesting again. Reducing the request rate alone does not resolve this error. | | `1807` | Node | The subscription quota for the current period is exhausted | Check the plan and period quota. Wait for the quota to reset or upgrade through a supported plan change; a brief backoff does not replenish the total quota. | | `2001` | Address screening | No screening quota is available in the current plan | Refresh plan and quota information. Purchase, renew, or add quota before submitting again. | | `2101` | Swap | The swap receiving address already exists | Look up and use the existing address instead of adding it again. | | `2102` | Swap | The account's deposit address cannot be used as a swap receiving address | Use a receiving address that meets the requirements. | | `2103` | Swap | Payment cannot be retried for the order in its current state | Check the original order and payment status. Stop repeating the payment. | | `2104` | Swap | The swap order cannot be retried in its current state | Check the original order's status before using an available recovery action for this service. | | `9999` | General | System error during request processing | Read-only requests may be retried a limited number of times. Confirm the outcome before retrying orders or payments, and contact support if the problem persists. | Treat any unlisted nonzero code as a failure and retain its original value. Do not automatically sign the user out or resubmit orders or payments. Error messages are for display and should not control program logic. ## Seamless Energy and Node Response Formats Seamless Energy uses business codes `1201–1215`; Node uses `1801–1807`. Shared errors such as parameters, authentication, permissions, and balance still use public codes, including `1`, `100`, `101`, `102`, and `201`. An invalid API Key does not indicate an expired account login session and should not automatically sign the user out. * **Application JSON APIs:** Business errors typically retain HTTP 200; check the integer `code`. An address management query with no matching binding uses `112`, while a transaction owner that is not bound during broadcast authorization corresponds to `1202`. * **Node proxy:** Classified access rejections retain HTTP 403 or 429 and include a business code in the body. HTTP 429 may indicate a rate limit (`106`), an expired subscription (`1806`), exhausted total quota (`1807`), or a missing subscription record (`1804`). Handle the specific business code rather than treating every HTTP 429 as a temporary rate limit. * **Seamless Energy HTTP broadcast:** Failures retain the TRON format, typically HTTP 200 with `result=false`, a TRON `code`, and `message`. This `code` is not a business code from the table above. Original node errors use the node’s enum name, or the integer value for an unknown enum; original `message` bytes are hex-encoded according to the TRON format. Local rejections continue to use safe messages. * **Seamless Energy gRPC broadcast:** Failures may still return HTTP 200 and `grpc-status=0`. Check `TransactionReturn.result`, `code`, and `message`. Explicit node rejections preserve the original `TransactionReturn`. Do not interpret business codes as TRON enums or gRPC status values. Local errors in gRPC queries use a non-OK gRPC status. If the broadcast outcome is unknown or the connection drops, check the on-chain result using the original transaction hash before taking further action. Acceptance for broadcast does not mean the transaction has executed successfully on-chain. See [Seamless Energy API Integration](/en/seamless-energy/api-integration.md) for broadcast integration instructions. ## Retrying and Confirming Results 1. **Confirm the original outcome first.** Code `114`, a timeout, a network disconnection, or a system error does not prove that the operation did not occur. For orders or payments, check the original order and payment records. Contact support if the outcome remains unclear. 2. **Address the reported cause.** Correct parameter or authentication errors before resubmitting. Do not repeatedly submit an unchanged request when permissions are insufficient, the account is disabled, or the current business state does not allow the operation. Temporary failures of read-only requests may be retried after a delay, with limits on retry count and frequency. 3. **Follow the endpoint's idempotency contract.** For operations that support idempotency, keep the same account, original idempotency ID, and business parameters when retrying. Generate a new timestamp and signature. Do not use a new ID to retry the same purchase. If idempotency support is unconfirmed, do not automatically resubmit orders or payments. 4. **Continue checking business status.** Returning an existing order or `code=0` does not mean payment has succeeded or the service has been delivered. Check the relevant business status. See [API Overview](/en/getting-started/buy-energy-via-api-on-catfee/api-overview.md) for signature rules and [API Supports Idempotency](/en/getting-started/api-supports-idempotent-requests.md) for energy purchase parameters and examples. ## Troubleshooting and Support When contacting support, include the environment, request time, HTTP method and path, HTTP status, `code` / `msg`, order `id`, `client_order_id`, and the response's `X-Request-ID` if present. Redact sensitive request information. Do not send API Secrets, full signatures, tokens, passwords, or verification codes. Contact: [@CatFee\_James](https://t.me/CatFee_James).