API 参考

错误码

网关自身生成的错误使用以下响应结构：

{
  "error": {
    "message": "invalid api key",
    "code": "invalid_api_key"
  }
}

程序逻辑应使用 HTTP 状态和 error.code。error.message 仅用于诊断，部分消息会包含当前请求的具体信息。网关自身生成的错误不包含 error.type。

请求到达网关后，响应还会包含 X-Request-Id。请保留该值，以便在调用日志中查询或提交支持请求。

请求与策略错误

HTTP error.code 含义 处理方式
400 invalid_body 网关无法读取请求体 发送可读取的请求体，并检查 Content-Length 或传输编码
400 model_not_allowed API Key 不允许调用所选模型 选择允许的模型，或调整 Key 的模型范围
400 max_output_tokens_exceeded 请求的输出 Token 预算超过 Key 策略 降低 max_tokens 或 max_output_tokens，或调整 Key 策略
401 missing_platform_authorization 请求没有携带 API Key 发送 Authorization: Bearer $APIGO_API_KEY
401 invalid_api_key API Key 不存在或当前无法解析 检查 Bearer Token，并在 API Keys 中确认 Key 已启用
402 quota_exceeded API Key 被标记为额度已耗尽 检查该 Key 的状态与额度配置后再重试
402 insufficient_balance Workspace 没有正数可用资金 充值或提高已配置授信，并等待准入快照刷新
402 day_limit_reached API Key 已达到当日消费额度 等待 Workspace 时区的下一个自然日，或提高上限
402 d7_limit_reached API Key 已达到滚动 7 日花费上限 等待历史消费移出窗口，或提高上限
402 d30_limit_reached API Key 已达到滚动 30 日花费上限 等待历史消费移出窗口，或提高上限
403 apikey_inactive API Key 不是启用状态 启用该 Key，或改用其他有效 Key
405 method_not_allowed 使用了 GET 以外的方法请求 /v1/models 使用 GET /v1/models
429 hydrate_cooldown API Key 状态刷新暂处于冷却期 退避后重试
429 api_key_rpm_exceeded 当前 API Key 的 RPM 容量已用尽 遵守 Retry-After 并降低该 Key 请求速率
429 api_key_tpm_exceeded 当前 API Key 的 TPM 容量已用尽 遵守 Retry-After 并降低该 Key Token 速率
429 api_key_concurrency_exceeded 当前 API Key 的并发容量已用尽 等待该 Key 的进行中请求完成
429 workspace_rpm_exceeded Workspace 共享 RPM 容量已用尽 遵守 Retry-After 并降低 Workspace 总请求速率
429 workspace_tpm_exceeded Workspace 共享 TPM 容量已用尽 遵守 Retry-After 并降低 Workspace 总 Token 速率
429 workspace_concurrency_exceeded Workspace 共享并发容量已用尽 等待 Workspace 内进行中的请求完成

网关服务错误

以下错误通常需要排查平台或供应商服务。对瞬时失败使用有上限的指数退避；如果持续出现，请携带 X-Request-Id 联系支持。

HTTP error.code 含义
500 identifier_generation_failed 网关无法生成请求 ID
500 resolver_not_configured API Key 解析器不可用
500 local_quota_not_configured 本地配额协调器不可用
502 auth_resolve_failed 网关无法解析 API Key 状态
502 rate_limit_config_invalid 解析到的限流配置无效
502 missing_upstream_base_url 解析到的供应商地址缺失
502 invalid_upstream_base_url 解析到的供应商地址无效
502 upstream_request_failed 网关无法完成供应商请求

上游透传错误

供应商响应会保留原始 HTTP 状态和响应体。error.type、error.code 与 error.message 取决于具体供应商，也可能不存在。

rate_limited、upstream_unavailable 等错误码并非当前 Gateway 自身生成。仅当上游实际响应包含这些值时，才按对应供应商的语义处理。

余额、消费额度与两层运行配额的关系见限额与请求准入。

排查顺序

  1. 先按 HTTP 状态和 error.code 判断失败类别
  2. 保存 X-Request-Id
  3. 在调用日志中查找该请求
  4. 对请求类错误修复 API Key、模型策略、花费上限或请求参数
  5. 对瞬时的上游或服务错误使用有上限的退避重试
Previous
限流