# 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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catfee.io/en/getting-started/faq.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.