Skip to main content
ApiGo 模型 API 使用 HTTP 状态码表示请求结果。错误响应的具体字段会遵循你所调用 endpoint 的兼容协议，但状态码的含义和建议处理方式保持一致。 不要依赖完整的错误文案进行程序判断。优先使用 HTTP 状态码，以及响应中存在的结构化错误类型或错误代码。

​
HTTP 状态码

​
理解 402 和 429

402 和 429 都可能表示当前请求受到用量或容量约束，但处理方式不同：
  • 请求频率或并发限制：降低请求速度，并使用指数退避重试。
  • 账户余额不足：充值后再重试。持续自动重试不会解决问题。
  • API 密钥用量限制：提高该密钥的限额，或等待当前限额周期结束。
不同 endpoint 的结构化错误字段可能不同。请结合 HTTP 状态码、响应中的错误类型或错误代码，以及错误文案判断具体原因。 更多限流建议请参阅速率限制。

​
响应格式

错误响应会遵循所调用 endpoint 的兼容协议，而不是所选模型或上游服务的协议。随着 ApiGo 接入新的模型或上游服务，你不需要为每个 provider 增加新的错误处理分支。 不同兼容协议可能使用 type、code 或 status 等不同字段。它们不是一套跨 endpoint 通用的枚举。 使用对应 endpoint 的 API 定义或 SDK 类型处理具体响应结构。

​
流式请求

流式请求可能以两种方式失败：
  • 如果错误发生在流开始之前，API 会返回正常的 HTTP 错误状态和错误响应体。
  • 如果错误发生在流开始之后，HTTP 状态可能已经是 200，错误会作为事件出现在数据流中。
客户端应持续读取数据流直到正常结束，并将流中的错误事件视为请求失败。不要只根据最初的 HTTP 200 判断流式请求成功。

​
重试与排障

  • 不要自动重试 400、401、402、403、404 或 413，除非你已经修正对应问题。
  • 只有在 429 表示请求频率限制时才自动重试；余额或密钥限额问题需要先处理账户配置。
  • 对 503 使用有限次数的指数退避重试，并加入随机抖动，避免大量客户端同时重试。
  • 记录请求时间、endpoint、HTTP 状态码和结构化错误类型。响应中存在 x-apigo-request-id 时也一并记录。
  • 不要在日志或工单中记录完整的 API 密钥。