跳转到主要内容
错误响应主要由 HTTP 状态码、error.type、error.code、error.message 以及 X-Request-Id 组成。

​
错误响应结构

  • HTTP 状态码：表示本次请求最终失败类别。
  • X-Request-Id：请求追踪 ID。如果客户端未传入，网关会自动生成；失败响应会尽量回传该值。
  • error.message：面向调用方的可读错误描述。
  • error.type：错误类型。ApiGo网关返回的稳定错误当前固定为 invalid_request_error；上游平台返回的错误类型可能不同。
  • error.code：错误码。ApiGo网关会返回稳定 code；上游平台返回的错误可能没有该字段。
Example response
{
  "error": {
    "message": "upstream provider credentials unavailable",
    "type": "invalid_request_error",
    "code": "missing_upstream_key"
  }
}

​
错误来源

​
ApiGo网关

error.codeHTTP 状态码error.typeerror.message含义
missing_upstream_key502invalid_request_errorupstream provider credentials unavailable上游服务当前不可用，请联系平台管理员检查供应商凭证配置。
invalid_upstream_key_info502invalid_request_errorinvalid key info response上游服务配置数据无效，当前无法完成请求。
masked_upstream_key502invalid_request_errorupstream provider credentials are masked and cannot be used上游服务凭证不可用，当前无法完成请求。

​
上游平台错误

部分请求会直接返回上游平台的错误响应。此时你应以返回的 HTTP 状态码和 error 对象为准。
  • HTTP 状态码：以实际返回值为准。
  • 响应体：通常包含平台返回的 error.type、error.code、error.message。
  • X-Request-Id：可用于问题排查和日志检索。
  • 文档边界：不要把上游平台的所有 type 或 code 当成 ApiGo网关的稳定错误码。
Platform passthrough example
{
  "error": {
    "message": "daily credits exhausted",
    "type": "insufficient_quota"
  }
}
上面这个 402 示例表示额度或余额不足。它来自上游平台，不属于 ApiGo 网关的稳定错误码。

​
推荐排查顺序

  1. 先看 HTTP 状态码，确认是 MaaS 网关稳定错误，还是上游平台直接返回的错误。
  2. 再记录 X-Request-Id，用于日志检索和工单排查。
  3. 如果 error.code 是 missing_upstream_key、invalid_upstream_key_info、masked_upstream_key 之一，可联系平台管理员处理服务配置问题。
  4. 如果是上游平台错误，优先根据返回的 error.type、error.code、error.message 判断额度、鉴权或平台策略限制。