GetMyBot 知识库

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 EntityJSON 语法正确,但业务验证失败;也可能是同一 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 不会被记为可重放结果,因为它们表示操作没有完成。保留同一密钥重试时,服务器会重新执行;否则若把失败结果缓存一周,该密钥就无法完成操作。

使用步骤

  1. 第一次请求之前生成 UUID,并随任务保存。
  2. 用它发送请求。
  3. 断线、超时、5xx 或 429 后,用同一密钥和请求体重试。
  4. 收到 409 时,等待 Retry-After 后继续用同一密钥。
  5. 只有确实要执行另一项新操作时才换密钥。

每次重试都生成新密钥是常见错误:服务器会把每次尝试当作独立操作。

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 原始响应或访问令牌。

接下来