> 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?**

1. Save the returned `id` (order ID). `code=0` means the API request succeeded; `status=PAYMENT_SUCCESS` means delegation is pending or in progress, not complete.
2. Query `GET /v1/order/{id}`. `status=DELEGATE_SUCCESS` means the delegation transaction was submitted; check `confirm_status` for confirmation.
3. `confirm_status=DELEGATION_CONFIRMED` means delegation was confirmed on-chain.

For time-based rentals, the only normal `status` values are `PAYMENT_SUCCESS` and `DELEGATE_SUCCESS`; the only normal `confirm_status` values are `UNCONFIRMED` and `DELEGATION_CONFIRMED`. Treat all other values as failure. The `balance` field in order creation, order details, and early reclaim responses represents the user's current balance in SUN.

For time-based rentals, reclamation states are returned as `status=DELEGATE_SUCCESS`, and reclamation confirmation states as `confirm_status=DELEGATION_CONFIRMED`. Do not wait for a reclamation status. These values do not guarantee energy is still available: check expiry, reclamation details, and on-chain resources after the rental expires or is reclaimed early. See [Order Details](https://docs.catfee.io/en/api-reference/order-detail.md) for the full rules.

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

* Delegation may still be awaiting on-chain confirmation. If confirmation fails, the platform handles further processing; check the order confirmation status for updates.
* 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!
