> 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/faq.md).

# Frequently Asked Questions (FAQ)

### 1. Account & Permission Issues

**1.1 Why is my API key not working?**\
**Cause**: The API key may have been disabled or deleted.\
**Solution**: Log in to the [CatFee official website](https://catfee.io/) to check the status of your API key.

**1.2 How can I restrict API key access to specific IP addresses?**\
**Solution**: When creating or editing an API key, specify the IP address you wish to bind. This will restrict access to only that IP, improving security.

***

### 2. Signature & Authentication Issues

**2.1 Why am I receiving `401 Unauthorized`?**\
**Possible Causes**:

* Invalid `CF-ACCESS-KEY` or `CF-ACCESS-SIGN`.
* Incorrect signature generation.
* Timestamp deviation exceeds 5 seconds.

**Solution**:

* Ensure `CF-ACCESS-KEY`, `CF-ACCESS-PASSPHRASE` match those set when the API key was created.
* Make sure the signature follows [CatFee's signature rules](https://docs.catfee.io/).
* Confirm that `CF-ACCESS-TIMESTAMP` is a valid UTC timestamp and the deviation from server time is less than 5 seconds.

**2.2 How to verify signature generation?**\
**Solution**:

* Print the string to be signed (`timestamp + method + requestPath`).
* Compare the generated signature with one computed manually.
* You can use Postman or Curl for manual testing and comparison.

***

### 3. Request & Response Issues

**3.1 Why am I receiving `400 Bad Request`?**\
**Possible Causes**:

* Invalid or missing request parameters.
* Incorrect API path.

**Solution**:

* Check the API documentation to ensure parameters and paths are correct.
* Make sure the `Content-Type` header is set to `application/json`.
* Confirm the request body is in proper JSON format.

**3.2 Why am I receiving `429 Too Many Requests`?**\
**Cause**: Request rate exceeds the API limit.\
**Solution**:

* Read the API documentation to understand rate limits.
* Implement throttling in your code to stay within the allowed request frequency.
* In distributed environments, ensure the total request rate across systems doesn't exceed the limit.

**3.3 Why am I receiving `500 Internal Server Error`?**\
**Cause**: Temporary issue on the server side.\
**Solution**:

* Check network connectivity to ensure the request was successfully sent.
* Retry after a few seconds.
* If the issue persists, contact CatFee technical support.

***

### 4. Specific Endpoint Issues

**4.1 Why am I unable to place an order?**\
**Possible Causes**:

* Insufficient account balance.
* Invalid order parameters (e.g. price, amount).
* Trading permissions not enabled.

**Solution**:

* Ensure sufficient balance in your account.
* Check that order parameters (e.g. quantity, cycle) meet minimum order requirements—refer to the "Create Order" section of the documentation.

**4.2 How to verify that purchased energy has been delivered?**

* After placing an order, record the returned `id` (payment hash/order ID).
* When `status = TRANSFER_SUCCESS`, the order has been placed successfully.
* Typically, energy will be credited within **6 seconds** after a successful order.
* Use `/v1/order/{id}` to query the order `status`:
  * `TRANSFER_SUCCESS`: Order placed successfully
  * `DELEGATE_SUCCESS`: Energy delegated successfully
  * `RECLAIM_SUCCESS`: Energy reclaimed

When `status` is `DELEGATE_SUCCESS`, it means the energy transaction has been submitted to the TRON blockchain.\
Note: In rare cases (approx. 0.1%), the transaction might fail to be confirmed on-chain.

Check the blockchain confirmation via `confirm_status` in the order details (`/v1/order/{id}`):

* `DELEGATION_CONFIRMED`: Energy has been 100% successfully delivered and confirmed on-chain.

**4.3 Why are some orders taking longer to complete?**

* There is a very small chance (\~0.1%) that TRON transactions may not be confirmed on-chain. In such cases, the platform will automatically resend the energy.
* When platform energy supply is under heavy load, energy delivery may experience delays.

***

### 5. Development & Debugging Issues

**5.1 How to handle timeout issues?**\
**Possible Causes**:

* Network latency or unstable connection.

**Solution**:

* Set a longer timeout (e.g. `timeout = 30`).
* Implement retry logic for critical operations (e.g. retry 2–3 times).
* Check local network connectivity to CatFee API servers.

**5.2 How to parse API responses?**\
**Solution**: CatFee API responses are typically in JSON format:

```json
{
  "code": "0",
  "msg": "",
  "data": {
    "key": "value"
  }
}
```

* `code = 0` indicates success.
* Non-zero `code` values indicate errors.
* The main response data is inside the `data` field—parse JSON to retrieve specific values.

***

### 6. Other Issues

**6.1 Why does timestamp validation often fail?**\
**Cause**: Local time is not synced with UTC.\
**Solution**: Use `datetime.utcnow()` in Python (or equivalent in your language).

**6.2 How to handle API version upgrades?**\
**Solution**:

* Subscribe to CatFee developer announcements to stay updated.
* Regularly update your code to match the latest API versions.
* Use versioned APIs (e.g. `/v1/`) to avoid compatibility issues during upgrades.

***

### 7. Contact Support

If you still cannot resolve your issue, please contact CatFee technical support:

* **Submit a ticket**: CatFee Support Center
* **Developer Documentation**: [API Docs](https://docs.catfee.io/)

***

We hope this FAQ helps you quickly resolve common issues encountered when using the CatFee API!