# API 错误码与调用额度

## 调用额度 {#rate-limit}

V2 REST 的业务请求与管理端 MCP 的工具调用按组织共享频率和日额度。同一组织换 Key、成员或调用入口，仍使用同一份额度。不同操作有各自的频率和计量规则；MCP 的初始化、心跳和工具列表不计入业务调用。

发送 `POST /api/v2/rpc/usage/get`，请求体为 `{}`，或调用 MCP 的 `usage_get`，可查询当日已用、预占、剩余和重置时间。REST 遇限流返回 HTTP 429。查看 `data.error.code`：`rate_limited` 按返回的 `Retry-After`（秒）或 `retry_after_ms` 等待；`quota_exceeded` 先查剩余和重置时间。重试写入时保留原参数和幂等键。

## 顶层 `code`（通用）

- `0`：成功
- `400`：参数错误或业务错误
- `401`：API Key 无效（鉴权失败）
- `403`：凭证类型、授权档位或目标资源权限不满足接口要求，见[权限排查](https://cli.im/open-api/openapi/v2/auth.md#verify-key)
- `404`：资源不存在或无权限
- HTTP `429`：频率或额度受限。V2 组织限流响应体中的 `code` 是业务错误字符串。
- `502`：上游服务暂不可用

## 管理接口的业务错误码

生成二维码、编辑、删除、上传、标签导出等接口失败时，`code` 是字符串形式的业务错误码，如 `TEMPLATE_VERSION_CONFLICT`。全部错误码的含义和处理方式见[业务错误码](https://cli.im/open-api/openapi/v2/error-catalog.md)，每个接口常见的错误码列在它的[说明页](https://cli.im/open-api/openapi/v2/api-index.md)里。

## 业务错误 `error_code`（模块异常码）

当发生业务错误时，上游可能会返回 `error_code`。接口会将该 `error_code` 透传到响应体顶层 `error_code`（同时保留顶层 `code` 与 `message`）。

说明：若上游以非 `2xx` HTTP 状态返回错误，且错误响应体无法被解析，则可能仅表现为 `404/502` 等 HTTP 结果，此时响应体中未必包含 `error_code`。

下面是模块异常码（区间 `100300 ~ 100329`）：

| error_code | message | 中文说明 |
|------------|---------|----------|
| `100300` | `System error` | 系统错误（未归类的内部异常）。 |
| `100301` | `Invalid request parameters` | 请求参数无效（必填缺失、类型错误、参数值非法）。 |
| `100302` | `Unsupported version` | 版本不支持（`version` 无法识别）。 |
| `100303` | `Record not found` | 记录未找到（指定 `record_id` / `record_url` 无法定位记录）。 |
| `100304` | `Form not found` | 表单未找到（指定 `tpl_id` 无法找到对应表单）。 |
| `100305` | `Unsupported output format` | 输出格式不支持（`format` 参数无法识别）。 |
| `100306` | `Form not assigned to this code` | 二维码未关联该表单。 |
| `100307` | `Duplicate submission not allowed for this field` | 不允许重复提交（唯一性校验失败）。 |
| `100308` | `Required field is empty` | 必填字段为空（缺少必要字段或未填写）。 |
| `100309` | `Field validation failed` | 字段校验失败（字段值格式或内容不合法）。 |
| `100310` | `Submitted resource has expired` | 提交所依赖的资源已过期。 |
| `100311` | `User submission limit reached` | 用户提交次数达到上限。 |
| `100312` | `Form submission limit reached` | 表单提交次数达到上限。 |
| `100313` | `Submission not allowed at current time` | 当前时间不允许提交。 |
| `100314` | `Submission not allowed in current code state` | 当前二维码状态不允许提交。 |
| `100315` | `API key invalid or disabled` | API Key 无效或已禁用。 |
| `100316` | `API key org mismatch` | API Key 对应企业与请求不匹配。 |
| `100317` | `No codes found in the selected category` | 指定分类下没有可用二维码。 |
| `100318` | `Too many codes found in the selected category` | 命中二维码过多，超出系统限制。 |
| `100319` | `Certificate verification failed` | 通用凭证核销失败，未命中更细的核销错误场景。 |
| `100320` | `Invalid certificate code` | 凭证码无效，或无法定位对应凭证记录。 |
| `100321` | `Certificate verification is not enabled` | 表单或凭证未开启核销能力。 |
| `100322` | `Certificate record is not approved for verification` | 凭证记录尚未审核通过，暂不可核销。 |
| `100323` | `Certificate does not match the requested scope` | 凭证与请求中 `tpl_id` / `code_id` 限制范围不匹配。 |
| `100324` | `Certificate cannot be verified in current status` | 当前凭证状态不允许核销，或核销流程已经结束。 |
| `100325` | `Invalid verification action` | 核销动作不支持（如 `action_type` 非法），或该表单未启用对应核销方式。 |
| `100326` | `Invalid target certificate status` | 目标凭证状态无效、不存在，或没有可切换的下一状态。 |
| `100327` | `Invalid verification authorization code` | 核销授权码无效或已过期。 |
| `100328` | `No permission to verify this certificate` | 当前操作方没有核销该凭证的权限。 |
| `100329` | `Identity information required before verification` | 核销前需要先完善身份信息。 |
