API 错误
看懂 API 错误,判断何时修正请求、何时重试,以及如何安全重试付款或群发。
本页内容
请求失败时先看 HTTP 状态码:例如 401 表示访问问题,429 表示请求太频繁。响应中的 error 会说明具体原因。成功响应直接包含数据,没有额外的通用包装层。
错误格式
服务器以包含 error 文字的 JSON 对象报告错误:
{"error":"reaction not found"}
程序应主要依据 HTTP 状态码判断,error 文字用于日志和给用户的提示。
状态码
| HTTP 状态 | 含义 |
|---|---|
200 OK | 成功,响应体包含数据 |
201 Created | 已创建资源,适用于部分 POST 接口 |
204 No Content | 成功但没有响应体,适用于部分删除操作 |
400 Bad Request | 请求体或参数错误 |
401 Unauthorized | 令牌缺失、无效或过期,或此路径不支持个人令牌 |
402 Payment Required | 套餐或额度限制了操作,例如媒体库存储需要付费功能 |
403 Forbidden | 缺少令牌权限范围或工作区权限(missing cabinet right),见令牌所属工作区 |
404 Not Found | 资源不存在或不属于您 |
409 Conflict | 状态冲突(如唯一值重复),或同一 Idempotency-Key 的操作仍在执行 |
413 Payload Too Large | 请求体过大,见请求限制;带 Idempotency-Key 的操作另有 64 KiB 上限 |
422 Unprocessable Entity | JSON 语法正确,但业务验证失败;也可能是同一 Idempotency-Key 被用于不同的请求体 |
429 Too Many Requests | 请求频率超限,见请求限制 |
500 Internal Server Error | 服务器内部错误,稍后可重试 |
如何处理
将 2xx 视为成功。对于 401 或 403,检查令牌、权限范围和工作区权限。对于 429 和 5xx,可逐步延长间隔后重试。
其他 4xx 通常需要先修正请求,再发送。例外是带 Idempotency-Key 的请求收到 409:这表示同一操作正在执行,可能是付款或群发,而非已经失败。按响应中的 Retry-After 等待,再用相同密钥重试。
安全重试付款和发送:Idempotency-Key
密钥必须是带连字符的小写标准 UUID,例如 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d。其他格式返回 400。
哪些路径支持
以下操作可以不传此请求头,但为防止重复扣费或重复群发,建议传入:
POST /api/billing/topup:充值;POST /api/billing/subscribe:订阅套餐;POST /api/bots/{botID}/reactions/{reactionID}/broadcast:启动群发。
以下两种客服发送操作则必须传入,否则返回 400:
POST /api/bots/{botID}/users/{userID}/dialog/messages;POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates。
其他路径会忽略此请求头。它并非适用于整个 API 的防重复机制;不在列表中的接口,重试可能执行第二次。
服务器如何响应
- 同密钥、同请求体,首次操作已完成:返回第一次的状态码和响应体,另带
Idempotent-Replay: true。只执行一次,结果记录保留一周。 - 同密钥,首次操作仍在执行:返回
409和Retry-After;等待后用同一密钥重试。改用新密钥可能导致重复扣费。 - 同密钥,不同请求体:返回
422。请确认这是新操作后再生成新密钥。 - 请求体超过 64 KiB:返回
413。这些操作通常请求体很小,超限应检查客户端。
5xx、408、425 和 429 不会被记为可重放结果,因为它们表示操作没有完成。保留同一密钥重试时,服务器会重新执行;否则若把失败结果缓存一周,该密钥就无法完成操作。
使用步骤
- 第一次请求之前生成 UUID,并随任务保存。
- 用它发送请求。
- 断线、超时、
5xx或429后,用同一密钥和请求体重试。 - 收到
409时,等待Retry-After后继续用同一密钥。 - 只有确实要执行另一项新操作时才换密钥。
每次重试都生成新密钥是常见错误:服务器会把每次尝试当作独立操作。
AI 与流程设置错误
Managed AI 的错误原因包括 not_available(功能不可用)、not_entitled(没有权限)、budget_exceeded(预算用尽)、rate_limited(频率限制)、provider_unavailable(模型服务不可用)及 schema_validation_failed(输出不符合格式)。仅当响应允许时才用**同一 Idempotency-Key**重试。对于除 429 外的 4xx 或 Schema 验证失败,应修正请求;切换模型供应商不会解决 Schema 错误。
Copilot 返回 stale_base 表示提案基于旧版反应,请基于当前流程重新生成。分析规则已被其他请求修改时,修改会返回 409。重新计算分析和重放执行都属于有限范围的后台任务;启动新任务前先查看已有任务状态。Meta 连接检查会返回用于定位问题的原因代码,不会在错误中包含 Meta 原始响应或访问令牌。
接下来
- 身份验证与令牌:
401与403。 - 请求限制:
429与请求体大小。 - 交互式 API 参考:具体接口的错误。