API 错误码与调用额度
调用额度
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:凭证类型、授权档位或目标资源权限不满足接口要求,见权限排查404:资源不存在或无权限- HTTP
429:频率或额度受限。V2 组织限流响应体中的code是业务错误字符串。 502:上游服务暂不可用
管理接口的业务错误码
生成二维码、编辑、删除、上传、标签导出等接口失败时,code 是字符串形式的业务错误码,如 TEMPLATE_VERSION_CONFLICT。全部错误码的含义和处理方式见业务错误码,每个接口常见的错误码列在它的说明页里。
业务错误 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 | 核销前需要先完善身份信息。 |