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

​
HTTP 状态码

状态码含义建议处理
400请求参数无效、格式错误，或当前模型不支持该请求。修改请求后再重试。
401API 密钥缺失、无效或已停用。检查鉴权方式和 API 密钥。
402账户余额不足。部分兼容协议会使用该状态码。充值后再发起请求。
403API 密钥有效，但没有执行该请求的权限。检查模型权限、IP 白名单和密钥配置。
404请求的模型、任务或资源不存在，或当前密钥无权访问。检查模型名称、资源 ID 和调用时使用的 API 密钥。
429命中请求频率限制、账户余额不足或 API 密钥用量限制。根据错误内容决定退避重试、充值、调整限额或等待下一个周期。
503ApiGo 或上游服务暂时无法处理请求。使用指数退避和随机抖动重试。

​
理解 402 和 429

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

​
响应格式

错误响应会遵循所调用 endpoint 的兼容协议，而不是所选模型或上游服务的协议。随着 ApiGo 接入新的模型或上游服务，你不需要为每个 provider 增加新的错误处理分支。 不同兼容协议可能使用 type、code 或 status 等不同字段。它们不是一套跨 endpoint 通用的枚举。
信息稳定性与用法
HTTP 状态码作为第一层处理依据。
结构化错误类型或代码按当前 endpoint 的 API 定义或 SDK 类型处理，不要跨 endpoint 假设字段名和值相同。
错误文案用于展示和排障，不要依赖完整文案进行程序判断。
补充排障信息可能不存在或被脱敏，不应作为业务逻辑依赖。
使用对应 endpoint 的 API 定义或 SDK 类型处理具体响应结构。

​
流式请求

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

​
重试与排障

  • 不要自动重试 400、401、402、403 或 404，除非你已经修正对应问题。
  • 只有在 429 表示请求频率限制时才自动重试；余额或密钥限额问题需要先处理账户配置。
  • 对 503 使用有限次数的指数退避重试，并加入随机抖动，避免大量客户端同时重试。
  • 记录请求时间、endpoint、HTTP 状态码和结构化错误类型。响应中存在 x-apigo-request-id 时也一并记录。
  • 不要在日志或工单中记录完整的 API 密钥。
为保护平台和上游服务信息，部分错误会被归一化为通用的 503。这类响应不会公开内部或上游的具体失败原因。