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

# 使用限制

> Flashduty Open API 使用限制与错误码说明

## 请求限制

***

### 频率限制

为保证服务稳定性，API 对请求频率有一定限制。当请求过于频繁时，将返回 `429` 状态码和 `RequestTooFrequently` 错误。

<Warning>
  请合理控制请求频率，避免在短时间内发送大量请求。建议实现重试机制，在收到 429 错误时进行指数退避重试。
</Warning>

### 权限限制

* 选择 **全部权限** 的 APP Key 不额外限制接口范围，但仍受创建者当前角色权限约束
* 选择 **自定义权限** 时，必须至少选择一个 API 权限点，APP Key 只能调用选中的接口范围
* 操作超出 APP Key 权限范围或创建者角色权限时，将返回 `403` 状态码和 `AccessDenied` 错误
* 建议为不同用途创建独立的 APP Key，遵循最小权限原则

***

## 错误码列表

***

| 错误码                    | HTTP Status | 描述                                      |
| ---------------------- | :---------: | --------------------------------------- |
| `InvalidParameter`     |     400     | 参数错误，请检查请求参数是否正确                        |
| `InvalidContentType`   |     400     | Content-Type 不支持，请使用 `application/json` |
| `MethodNotAllowed`     |     400     | HTTP Method 不支持                         |
| `Unauthorized`         |     401     | 登录认证未通过，请检查 APP Key 是否正确                |
| `AccessDenied`         |     403     | 权限认证未通过，当前用户无此操作权限                      |
| `RouteNotFound`        |     404     | 请求 Method + Path 未匹配，请检查 API 地址         |
| `RequestTooFrequently` |     429     | 请求过于频繁，请稍后重试                            |
| `ResourceNotFound`     |     400     | 账户未购买资源，请前往费用中心下单                       |
| `NoLicense`            |     400     | 账户无充足订阅 License，请前往费用中心升级或购买订阅          |
| `InternalError`        |     500     | 内部或未知错误，请联系技术支持                         |

***

## 错误处理建议

***

<AccordionGroup>
  <Accordion title="400 参数错误">
    **可能原因**：

    * 缺少必填参数
    * 参数格式不正确
    * Content-Type 未设置为 `application/json`

    **解决方案**：
    检查请求参数和 Headers 设置，参考 API 文档确认参数要求。
  </Accordion>

  <Accordion title="401 认证失败">
    **可能原因**：

    * APP Key 未提供
    * APP Key 不正确或已失效

    **解决方案**：

    1. 确认请求 URL 中包含 `app_key` 参数
    2. 前往控制台检查 APP Key 是否有效
  </Accordion>

  <Accordion title="403 权限不足">
    **可能原因**：

    * 当前用户无权执行此操作
    * APP Key 对应用户权限不足

    **解决方案**：
    联系账户管理员提升权限，或使用具有相应权限的 APP Key。
  </Accordion>

  <Accordion title="429 请求过频">
    **可能原因**：

    * 短时间内发送了过多请求

    **解决方案**：

    1. 降低请求频率
    2. 实现指数退避重试机制
    3. 合并多个请求（如使用批量接口）
  </Accordion>

  <Accordion title="500 内部错误">
    **可能原因**：

    * 服务端内部异常

    **解决方案**：

    1. 稍后重试
    2. 如持续出现，请联系技术支持并提供 `request_id`
  </Accordion>
</AccordionGroup>

***

## 最佳实践

***

<CardGroup cols={2}>
  <Card title="实现重试机制" icon="rotate">
    对于网络错误和 5xx 错误，建议实现指数退避重试，初始间隔 1 秒，最大重试 3 次。
  </Card>

  <Card title="记录 request_id" icon="clipboard-list">
    保存每次请求返回的 `request_id`，便于问题排查和技术支持。
  </Card>

  <Card title="保护 APP Key" icon="shield-check">
    不要在客户端代码中硬编码 APP Key，建议通过环境变量或配置中心管理。
  </Card>

  <Card title="定期轮换密钥" icon="key">
    定期更换 APP Key，及时删除不再使用的密钥，降低泄露风险。
  </Card>
</CardGroup>