> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Flashduty Open API rate limits and error codes

## Request Limits

***

### Rate Limits

To ensure service stability, APIs have rate limits on request frequency. When requests are too frequent, a `429` status code with `RequestTooFrequently` error will be returned.

<Warning>
  Please control your request frequency reasonably and avoid sending a large number of requests in a short period. It is recommended to implement a retry mechanism with exponential backoff when receiving a 429 error.
</Warning>

### Permission Limits

* An APP Key with **All permissions** has no additional API-scope restriction, but remains limited by the creator's current role permissions
* **Custom permissions** requires at least one selected API permission; the APP Key can call only APIs in that selected scope
* When an operation exceeds either the APP Key scope or the creator's role permissions, a `403` status code with `AccessDenied` error is returned
* It is recommended to create separate APP Keys for different purposes, following the principle of least privilege

***

## Error Code List

***

| Error Code             | HTTP Status | Description                                                                                                                  |
| ---------------------- | :---------: | ---------------------------------------------------------------------------------------------------------------------------- |
| `InvalidParameter`     |     400     | Parameter error, please check if request parameters are correct                                                              |
| `InvalidContentType`   |     400     | Content-Type not supported, please use `application/json`                                                                    |
| `MethodNotAllowed`     |     400     | HTTP Method not supported                                                                                                    |
| `Unauthorized`         |     401     | Authentication failed, please check if the APP Key is correct                                                                |
| `AccessDenied`         |     403     | Permission denied, current user does not have permission for this operation                                                  |
| `RouteNotFound`        |     404     | Request Method + Path not matched, please check the API address                                                              |
| `RequestTooFrequently` |     429     | Request too frequent, please try again later                                                                                 |
| `ResourceNotFound`     |     400     | Account has not purchased resources, please go to the billing center to place an order                                       |
| `NoLicense`            |     400     | Account does not have sufficient subscription License, please go to the billing center to upgrade or purchase a subscription |
| `InternalError`        |     500     | Internal or unknown error, please contact technical support                                                                  |

***

## Error Handling Recommendations

***

<AccordionGroup>
  <Accordion title="400 Parameter Error">
    **Possible causes**:

    * Missing required parameters
    * Incorrect parameter format
    * Content-Type not set to `application/json`

    **Solution**:
    Check request parameters and Headers settings, refer to API documentation for parameter requirements.
  </Accordion>

  <Accordion title="401 Authentication Failed">
    **Possible causes**:

    * APP Key not provided
    * APP Key is incorrect or has expired

    **Solution**:

    1. Confirm that the request URL contains the `app_key` parameter
    2. Go to the console to check if the APP Key is valid
  </Accordion>

  <Accordion title="403 Permission Denied">
    **Possible causes**:

    * Current user does not have permission to perform this operation
    * The user corresponding to the APP Key has insufficient permissions

    **Solution**:
    Contact the account administrator to elevate permissions, or use an APP Key with the appropriate permissions.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    **Possible causes**:

    * Too many requests sent in a short period

    **Solution**:

    1. Reduce request frequency
    2. Implement exponential backoff retry mechanism
    3. Combine multiple requests (e.g., use batch APIs)
  </Accordion>

  <Accordion title="500 Internal Error">
    **Possible causes**:

    * Server-side internal exception

    **Solution**:

    1. Retry later
    2. If the issue persists, contact technical support and provide the `request_id`
  </Accordion>
</AccordionGroup>

***

## Best Practices

***

<CardGroup cols={2}>
  <Card title="Implement Retry Mechanism" icon="rotate">
    For network errors and 5xx errors, it is recommended to implement exponential backoff retry with an initial interval of 1 second and a maximum of 3 retries.
  </Card>

  <Card title="Record request_id" icon="clipboard-list">
    Save the `request_id` returned from each request to facilitate troubleshooting and technical support.
  </Card>

  <Card title="Protect APP Key" icon="shield-check">
    Do not hardcode APP Key in client code. It is recommended to manage it through environment variables or configuration centers.
  </Card>

  <Card title="Rotate Keys Regularly" icon="key">
    Regularly replace APP Keys and promptly delete keys that are no longer in use to reduce the risk of leakage.
  </Card>
</CardGroup>