> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apigo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码查询

> API 指引中的错误码查询页，帮助快速定位请求失败原因。

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

## 错误响应结构

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

```json Example response theme={null}
{
  "error": {
    "message": "upstream provider credentials unavailable",
    "type": "invalid_request_error",
    "code": "missing_upstream_key"
  }
}
```

## 错误来源

### MaaS 网关

| `error.code`                | HTTP 状态码 | `error.type`            | `error.message`                                               | 含义                           |
| --------------------------- | -------- | ----------------------- | ------------------------------------------------------------- | ---------------------------- |
| `missing_upstream_key`      | `502`    | `invalid_request_error` | `upstream provider credentials unavailable`                   | 上游服务当前不可用，请联系平台管理员检查供应商凭证配置。 |
| `invalid_upstream_key_info` | `502`    | `invalid_request_error` | `invalid key info response`                                   | 上游服务配置数据无效，当前无法完成请求。         |
| `masked_upstream_key`       | `502`    | `invalid_request_error` | `upstream provider credentials are masked and cannot be used` | 上游服务凭证不可用，当前无法完成请求。          |

### 上游平台错误

部分请求会直接返回上游平台的错误响应。此时你应以返回的 HTTP 状态码和 `error` 对象为准。

* HTTP 状态码：以实际返回值为准。
* 响应体：通常包含平台返回的 `error.type`、`error.code`、`error.message`。
* `X-Request-Id`：可用于问题排查和日志检索。
* 文档边界：不要把上游平台的所有 `type` 或 `code` 当成 MaaS 网关的稳定错误码。

```json Platform passthrough example theme={null}
{
  "error": {
    "message": "daily credits exhausted",
    "type": "insufficient_quota"
  }
}
```

上面这个 `402` 示例表示额度或余额不足。它来自上游平台，不属于 MaaS 网关的稳定错误码。

## 推荐排查顺序

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` 判断额度、鉴权或平台策略限制。