# 错误码与请求标识

来源: https://platform.lyrouter.com/ai_gateway/docs/errors
更新日期: 2026-10-19

LYRouter 拒绝一次调用时返回 4xx 或 5xx 状态码。OpenAI 兼容接口的错误体是 `{"error": {"message", "type", "code"}}`，`/v1/messages` 上转换为 Anthropic 格式，另有少数响应是 HTML 页面或一行纯文本。按状态码和 `error.message` 原文在本页速查表中找到条目，就能判断问题出在请求本身、账户与配置，还是平台或上游服务商，以及该怎么处理。网关不在响应头里返回请求 ID，需要定位某次调用时，请到 **日志分析** 打开这次请求的详情，复制顶部的 Request ID。

## 错误响应格式

### OpenAI 兼容格式

除 `/v1/messages` 外，各接口（Chat Completions、Responses、Embeddings、图像、视频等）的错误体默认是：

```json
{
  "error": {
    "message": "insufficient credit balance",
    "type": "insufficient_quota",
    "code": "insufficient_credit_balance"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `message` | 报错原文，以英文为主，个别为中文。本页列出的原文与网关返回逐字一致，`<...>` 表示会被替换的部分 |
| `type` | 错误类别，如 `invalid_request_error`、`permission_error`、`access_denied`、`guardrail_blocked`、`insufficient_quota`、`rate_limit_error`、`billing_unavailable`、`service_unavailable`、`api_error` |
| `code` | 机器可读的标识，只有部分错误才有，没有时整个字段不出现。同一句 `message` 可能对应多个 `code`（如 `insufficient credit balance`），程序分支请优先按 `code` 判断 |
| 附加字段 | 个别错误才带：配额 429 的 `limit`、`used`、`reset_at` 等，熔断 429 的 `retry_after`、`blocked_until`，上游空响应体补全的 `upstream_status`、`generated_by` 等 |

### Anthropic 格式（`/v1/messages`）

通过 `/v1/messages` 调用时，网关自己的错误和上游的错误都会转换成 Anthropic 格式，`message` 保持原文：

```json
{
  "type": "error",
  "error": { "type": "authentication_error", "message": "invalid api key" }
}
```

| HTTP 状态码 | `error.type` |
| --- | --- |
| 400、402、422 | `invalid_request_error` |
| 401 | `authentication_error` |
| 403 | `permission_error` |
| 404 | `not_found_error` |
| 413 | `request_too_large` |
| 429 | `rate_limit_error` |
| 503、529 | `overloaded_error` |
| 500、502、504 及其他 5xx | `api_error` |

转换后不再带 `error.code` 和附加字段（如 `limit`、`retry_after`），响应头照常保留。本页的报错原文在 `/v1/messages` 上同样适用，需要区分具体原因时，以「状态码 + `message`」为准，或在日志中查看这次请求。

上表的 404 → `not_found_error` 不适用于路径或 HTTP 方法不存在的 404：例如用 GET 调用 `/v1/messages`，返回的是 404 `{"error_msg":"404 Route Not Found"}`，不转换为 Anthropic 格式。

### 不是 JSON 错误体的响应

| 情形 | 状态码 | 响应体 |
| --- | --- | --- |
| 连接上游失败、等待上游超时 | 500、504 | HTML 错误页 |
| `Content-Type` 不对、multipart 请求格式不对、要求的原生直通无法满足（`/v1/messages` 上转换为 Anthropic 格式，见上文） | 400 | 一行纯文本，如 `unsupported content-type: text/plain, only application/json is supported` |
| 工作空间设置了默认模型，而请求体不是合法 JSON 或为空 | 400 | `{"message": "..."}`，外层没有 `error` |
| 路径或 HTTP 方法不存在，如 `/v1/v1/chat/completions`、用 GET 调用 `/v1/chat/completions` | 404 | `{"error_msg": "404 Route Not Found"}` |

目前网关返回的纯文本 400，响应头 `Content-Type` 仍是 `application/json`，直接按 JSON 解析会失败，部分 SDK 会报「无法解析响应」。稳妥的做法是先看状态码，再判断正文是否为 JSON（尝试解析），能解析时依次取 `error.message`、`message`、`error_msg`，都取不到时记录响应原文的前几百个字符：

**读取错误响应**

cURL:
```bash
# -i 同时输出状态行和响应头（如 Retry-After、x-aigw-quota-*）
curl -sS -i https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"你好"}]}'
```

Python:
```python
import os
import requests  # 需要先 pip install requests，OpenAI SDK 不附带

resp = requests.post(
    "https://api.lyrouter.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={"model": "MODEL_ID", "messages": [{"role": "user", "content": "你好"}]},
    timeout=400,  # 长于网关等待上游的 6 分钟
)
if resp.status_code >= 400:
    try:
        body = resp.json()
    except ValueError:  # HTML 错误页或纯文本
        body = {}
    err = body.get("error", body) if isinstance(body, dict) else {}
    message = err.get("message") or err.get("error_msg") or resp.text[:300]
    print(resp.status_code, err.get("code"), message)
```

Node.js:
```js
const resp = await fetch("https://api.lyrouter.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "MODEL_ID", messages: [{ role: "user", content: "你好" }] }),
});
if (!resp.ok) {
  const text = await resp.text();
  let err = {};
  try {
    const body = JSON.parse(text);
    err = body.error ?? body;
  } catch {
    // HTML 错误页或纯文本
  }
  console.log(resp.status, err.code, err.message ?? err.error_msg ?? text.slice(0, 300));
}
```

## 速查表

「谁来处理」中的「管理员」指当前账号管理员或工作空间管理员，「联系支持」表示需要平台处理。

| 状态码 | 报错原文（`error.message`） | `error.code` | 原因 | 谁来处理 |
| --- | --- | --- | --- | --- |
| 400 | `you must provide a model parameter` | `missing_model` | 没写 `model`，工作空间也没有默认模型 | 调用方 |
| 400 | `invalid type for 'model': expected a string` | `invalid_model` | `model` 不是字符串 | 调用方 |
| 400 | `request body must be a JSON object` | `invalid_json` | 请求体不是合法的 JSON 对象；部分版本返回 `missing_model` | 调用方 |
| 400 | `could not get parse JSON request body: <解析错误>` | —（外层无 `error`） | 同上，工作空间设置了默认模型时 | 调用方 |
| 400 | `unsupported content-type: <类型>, only application/json is supported` | —（纯文本） | `Content-Type` 不是 JSON | 调用方 |
| 400 | ``multipart body has no non-empty `model` field`` 等 | —（纯文本） | multipart 请求体缺字段或取值不对 | 调用方 |
| 400 | `This model does not support the <接口> API` 等 | `unsupported_model_api` 等 | 模型不支持该接口、操作或输入类型 | 调用方换模型 |
| 400 | `unsupported parameters for this model: <参数名>` | `unsupported_parameters` | 严格模式下传了模型不支持的参数 | 调用方 |
| 400 | 具体参数的校验原文 | `invalid_parameter` | 图像、视频等接口的参数或 multipart 内容不合法 | 调用方 |
| 400 | ``native passthrough was required by `x-gateway-passthrough: require` ...`` | —（`/v1/messages` 上为 Anthropic 格式，其他接口为纯文本） | 要求原生直通，但这次请求无法直通 | 调用方 |
| 401 | `missing credentials` | — | 没带 API Key | 调用方 |
| 401 | `invalid authorization scheme, expected 'Bearer'` | — | `Authorization` 头格式不对 | 调用方 |
| 401 | `invalid api key` | — | Key 不存在、已删除、停用或过期 | 调用方 / 管理员 |
| 401 | `api key verification unavailable` | — | 平台密钥校验服务暂时不可用 | 稍后重试 |
| 402 | `insufficient credit balance` | `insufficient_credit_balance` 等 | 账户余额不足 | 账号管理员充值 |
| 402 | `subscription expired; renew to continue` | — | 订阅已到期 | 账号管理员续费 |
| 403 | `api key expired` | — | Key 已过有效期 | 新建 Key |
| 403 | `your IP address is not allowed` | — | 来源 IP 不在 Key 的白名单中 | 调用方 / Key 创建者 |
| 403 | `ip access control misconfigured` | — | Key 的 IP 白名单无效 | Key 创建者 |
| 403 | `api key workspace is unavailable` | — | 暂时读不到工作空间配置 | 稍后重试 |
| 403 | `Model is not available in the model plaza` | `model_not_available` | 工作空间没有开通该模型 | 管理员 / 换模型 |
| 403 | `Request blocked by guardrail policy` | `guardrail_*` | 请求被安全围栏拦截 | 调用方 / 管理员 |
| 403 | `Response blocked by guardrail policy` | `guardrail_sensitive` | 模型的回答被安全围栏拦截 | 调用方 / 管理员 |
| 403 | `Subject is blocked by an active security ban` | `guardrail_subject_banned` | Key 被安全围栏封禁 | 管理员 |
| 403 | `该 API Key 已被永久封禁，无法恢复，请删除后创建新的 API Key。` | `api_key_permanently_banned` | Key 第 5 次触发错误率熔断 | 修复程序后新建 Key |
| 404 | `404 Route Not Found`（字段为 `error_msg`） | — | 路径或 HTTP 方法不对 | 调用方 |
| 404 / 409 | `video task not found`、`video is not ready yet` 等 | `not_found` 等 | 视频任务不存在、未完成或不能取消 | 调用方 |
| 429 | `rate limit exceeded on <对象> <指标>/<窗口>` | — | 配额或预算已用完 | 等待重置 / 管理员调额 |
| 429 | `API Key 因最近 60 秒错误率过高已临时熔断，请在 N 秒后重试。` | `api_key_circuit_open` | Key 错误率过高被临时熔断 | 修复后按 `Retry-After` 等待 |
| 429 | `all upstream credentials for this model are rate limited` | `upstream_quota_exhausted` | 该模型所有上游凭证都达到限额 | 稍后重试 / 换模型 |
| 429 | `upstream concurrency full` | `upstream_concurrency_full` | 异步任务的上游并发已满 | 稍后重试 |
| 500 | HTML 错误页 | — | 连接上游失败或读取响应出错 | 稍后重试 |
| 500 | `sync spec needs the upstream model name for the path` 等 | `model_unresolved` 等 | 平台侧通道配置问题 | 联系支持 |
| 503 | `all routed candidates exhausted` | `no_route_candidate` | 找不到可服务的模型或通道 | 调用方 / 管理员 |
| 503 | `No configured credential can serve this model` | `no_route_candidate` | 该模型没有可用凭证 | 管理员 |
| 503 | `Workspace model projection is unavailable` | `workspace_model_projection_unavailable` | 暂时读不到工作空间的模型配置 | 稍后重试 |
| 503 | `billing balance is temporarily unavailable` | `billing_maintenance` 等 | 暂时无法确认账户余额 | 平台（部分可稍后重试，持续出现时联系支持） |
| 503 | `Platform supplier cost snapshot is unavailable` | `supplier_cost_snapshot_not_ready` | 该模型的通道价格未就绪 | 换模型并联系支持 |
| 504 | HTML 错误页 | — | 等待上游响应超时 | 稍后重试 |
| 上游的状态码 | 上游的报错原文 | 上游定义，或 `upstream_*` | 上游服务商拒绝了请求 | 视原文而定 |

## 400：请求格式或参数

本节的 400 都由网关在把请求发往上游之前返回。

### 模型字段与请求体

| 报错原文 | `error.code` | 含义与处理 |
| --- | --- | --- |
| `you must provide a model parameter` | `missing_model` | `model` 缺失、为 `""` 或 `null`（请求体为空时同样如此），且工作空间没有在 **智能路由** 中设置默认模型。在请求中写上模型 ID，可用 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) 查询 |
| `invalid type for 'model': expected a string` | `invalid_model` | `model` 写成了数字、对象等。设置了默认模型也不会顶替，请改成字符串形式的模型 ID |
| `request body must be a JSON object` | `invalid_json` | 请求体是字符串、数字等合法 JSON，但不是对象；请求体不是合法 JSON 时，原文为 `could not get parse JSON request body: <解析错误>`，`error.code` 同样是 `invalid_json`。部分版本对这两种请求体都返回 `you must provide a model parameter`（`missing_model`）；请求体是 JSON 数组时也返回 `missing_model`。检查引号、逗号和转义，以及请求体是否真的放进了 `-d` / `json=` |
| `could not get parse JSON request body: <解析错误>`（原文如此） | — | 工作空间设置了默认模型时，非法 JSON 返回这一句，响应体为 `{"message": "..."}`；请求体为空时是 `could not get body: request body is empty`。处理同上 |

设置了默认模型时，不写 `model` 的对话请求会改由默认模型回答，不会收到 `missing_model`。默认模型的设置见[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)。

### Content-Type 与 multipart（纯文本响应）

| 报错原文 | 含义与处理 |
| --- | --- |
| `unsupported content-type: <类型>, only application/json is supported` | 请求头 `Content-Type` 不是 `application/json`。JSON 接口请设置 `Content-Type: application/json`，不带这个头时按 JSON 处理。`/v1/images/edits` 和 `/v1/videos` 同时接受 JSON 和 `multipart/form-data` |
| ``multipart body has no non-empty `model` field`` | multipart 请求体里没有非空的 `model` 表单字段。工作空间没有默认模型时，先返回的是 `you must provide a model parameter` |
| `request body is empty` | multipart 请求体为空 |
| ``<字段> must be `true` or `false` in multipart form data`` | `/v1/videos` 的 multipart 请求中，`watermark`、`generate_audio` 只接受字面量 `true` 或 `false`，`1`、`yes`、`True` 都会被拒绝 |
| `input_reference must be a URL; uploading a file is not supported by this gateway (pass a publicly reachable https:// URL instead)` | `/v1/videos` 的 multipart 请求中，`input_reference`（参考视频）要传公网可访问的 `https://` 地址，不支持上传文件 |

### 模型不支持该接口或输入

`type` 为 `invalid_request_error`，按 `error.code` 区分：

| `error.code` | 报错原文 | 含义 |
| --- | --- | --- |
| `unsupported_model_api` | `This model does not support the <接口> API` | 模型不支持这一类接口，`<接口>` 为 `chat_completions`、`responses`、`embeddings`、`rerank`、`images`、`videos` 之一。例如用对话模型调用图像生成接口 |
| `unsupported_model_operation` | `This model does not support the <操作> operation` | 模型支持这一类接口，但不支持其中这个操作，如 `images_edits`、`videos_regenerations` |
| `unsupported_model_input` | `This model accepts text input only` | 给只接受文本的模型发送了图片、音频或文件 |

处理：在 **模型广场** 查看模型支持的接口与输入类型，换用支持的模型，见[模型能力与兼容性](https://platform.lyrouter.com/ai_gateway/docs/capabilities)。

### 参数不被支持或取值不合法

**`unsupported parameters for this model: <参数名>`（`unsupported_parameters`）**：请求带了 `X-Gateway-Strict-Parameters: true`，而请求中有所选模型不支持的参数。不带这个请求头时，网关丢弃这些参数照常调用，并在响应头 `X-Gateway-Unsupported-Parameters` 中列出参数名。这两个头目前只覆盖图像、视频接口；对话接口在跨协议转换时丢弃的参数（如 `response_format`、`seed`、`n`）既不触发这个错误，也不写这个响应头，见[网关扩展请求头与响应头](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers)。处理：删掉报错中列出的参数，或换用支持它们的模型。

**`invalid_parameter`**：`error.message` 直接说明是哪个参数、哪里不对，常见的有：

| 报错原文 | 含义 |
| --- | --- |
| `seconds must be a positive whole number of seconds` | 视频时长必须是正整数秒 |
| `watermark must be a boolean`、`generate_audio must be a boolean` | JSON 请求中这两个字段必须是布尔值 |
| `size implies an aspect ratio this model does not support: <取值>` | `size` 对应的宽高比该模型不支持 |
| `cannot read the multipart body`，或具体原因如 `truncated multipart body: no closing delimiter`、`inline file parts exceed the limit of 31457280 bytes` | 需要转换格式的模型读不出 multipart 请求体：请求体被截断、文件合计超过 30 MB 等 |
| `cannot rewrite the multipart model field: <原因>` | 网关无法把 multipart 中的 `model` 字段替换成上游的模型名，请求没有发出。确认 `model` 是普通文本字段；持续出现时联系支持 |

各参数的取值范围见[多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal)。

### 原生直通无法满足

原文：``native passthrough was required by `x-gateway-passthrough: require` but is not available for this request (<原因>)``

请求带 `x-gateway-passthrough: require` 表示「请求体必须原样发给 Anthropic 协议的上游，不允许转换」。网关做不到时直接拒绝，而不是悄悄转换；回退到非 Anthropic 协议的通道时也会以这个错误结束。在 `/v1/messages` 上，这个错误按 Anthropic 格式返回，`message` 与上面的原文一致：`{"type":"error","error":{"type":"invalid_request_error","message":"native passthrough …"}}`；在其他接口上是一行纯文本。括号里是否决的原因：

| 原因 | 含义 |
| --- | --- |
| `client_protocol` | 不是通过 `/v1/messages` 调用 |
| `route_disabled` | 接口没有开启请求侧原生直通 |
| `wire_protocol` | 选中的通道不是 Anthropic 协议上游 |
| `endpoint_type` | 不是对话接口 |
| `channel_disabled` | 该通道关闭了原生直通 |
| `preset_injection` | 使用的虚拟模型会改写请求体（追加系统提示词、设置或锁定参数、缓存策略） |
| `shape_oai` | 请求体不是 Anthropic 格式 |
| `decision_error` | 网关判定过程出错 |

目前 `/v1/messages` 没有开启请求侧原生直通，带这个请求头的请求会以 `route_disabled` 被拒绝。去掉这个请求头（或改为 `prefer`），请求即按正常的协议转换路径处理，见[Anthropic Messages](https://platform.lyrouter.com/ai_gateway/docs/anthropic-messages)。

## 401：鉴权失败

401 的请求无法归属到任何工作空间，日志中查不到。各条原因的详细排查见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

| 报错原文 | 含义与处理 |
| --- | --- |
| `missing credentials` | 请求没有携带 API Key。加上 `Authorization: Bearer <API Key>`，Anthropic 风格的客户端也可以用 `x-api-key: <API Key>`。通过环境变量配置的工具，修改后需要新开终端 |
| `invalid authorization scheme, expected 'Bearer'` | `Authorization` 头不是 `Bearer <API Key>` 格式。`Bearer` 区分大小写，`bearer sk-...`、直接写密钥、`Basic ...` 都会被拒绝；只写 `Bearer` 而没有密钥也返回这一句。同时带 `Authorization` 和 `x-api-key` 时只读 `Authorization` |
| `invalid api key` | 网关找不到这个 Key：复制不完整或带了空格、换行；Key 已删除、停用或过期；所属工作空间或创建人已停用；Key 刚创建、还没同步到网关（通常几秒）。被永久封禁的 Key 是例外：删除后仍返回 403 `api_key_permanently_banned`。重新复制完整的 Key，明文丢失时删除后新建，见[创建工作空间与 API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys) |
| `api key verification unavailable` | 平台的密钥校验服务暂时不可用，与 Key 是否正确无关。稍后重试，持续出现时查看[服务状态](https://platform.lyrouter.com/ai_gateway/docs/status) |

## 402：余额不足或订阅到期

| 报错原文 | `error.code` | 含义与处理 |
| --- | --- | --- |
| `insufficient credit balance` | `insufficient_credit_balance` | 账户 Credits 余额已用完；使用 BYOK 且需要支付平台服务费时，余额不足以支付服务费。由账号管理员在 **订阅充值** 充值 |
| `insufficient credit balance` | `balance_missing` | 账户还没有余额记录，通常是从未充值。充值后恢复；已充值仍出现时联系支持 |
| `insufficient credit balance` | `billing_entity_missing` | 网关找不到这个 Key 对应的计费账户，属于平台侧数据问题，联系支持 |
| `subscription expired; renew to continue` | — | 账户订阅已到期且已过宽限期，该账户下所有工作空间的调用都会被拒绝。续费后恢复；没有订阅的账户不会收到这个错误 |

`type` 为 `insufficient_quota`。余额检查发生在调用之前：余额大于 0 就能发起调用，一次调用可能把余额扣成负数，之后的调用才被拒绝。余额不足时网关不会改用其他通道或计费方式。计费规则见[计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing)。

## 403：访问被拒绝

### API Key 与来源

| 报错原文 | `error.code` | 含义与处理 |
| --- | --- | --- |
| `api key expired` | — | Key 已超过有效期，网关在每次请求时检查。新建一个 Key 替换它；过期一段时间后，同一个 Key 改为返回 401 `invalid api key` |
| `your IP address is not allowed` | — | Key 开启了 IP 白名单，请求的来源 IP 不在名单中（`type` 为 `permission_error`）。网关按到达时的出口 IP 判断，经公司网络、代理或云服务器调用时，出口 IP 可能与本机看到的不同 |
| `ip access control misconfigured` | — | Key 的 IP 白名单为空或含无效的 IP / CIDR，网关拒绝所有请求。由 Key 创建者或账号管理员修正白名单 |
| `api key workspace is unavailable` | — | Key 有效，但网关暂时读不到所属工作空间的配置，属于平台侧临时问题，稍后重试 |
| `该 API Key 已被永久封禁，无法恢复，请删除后创建新的 API Key。` | `api_key_permanently_banned` | Key 第 5 次触发错误率熔断，被永久封禁，不能解除；删除旧 Key 后它仍返回同样的 403。刚触发封禁时原文是 `该 API Key 因多次高错误率请求已被永久封禁，无法恢复，请删除后创建新的 API Key。`，封禁同步到网关后改为本行原文。先修复持续报错的程序再新建 Key，否则新 Key 也会被熔断 |

永久封禁的响应头带 `X-RateLimit-Reason: api_key_permanently_banned`，被拒绝的请求不写入日志。

### 模型未开通

**`Model is not available in the model plaza`**（`model_not_available`，`type` 为 `access_denied`）：Key 所属工作空间的 **模型广场** 中，这个模型的所有服务商都处于未开通状态。

- 管理员在 **模型广场** 开通该模型，或调用方改用已开通的模型。
- 在图像、视频接口上使用 `@vmodel/<名称>` 或 `lyrouter/auto` 也会返回这个错误：这些接口只接受具体的模型 ID。
- 工作空间设置了默认模型时，请求的模型未开通的对话请求通常改由默认模型回答，可在日志的「模型（实际）」中确认。详见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable)。

### 安全围栏

**`Request blocked by guardrail policy`**（`type` 为 `guardrail_blocked`）：请求命中了工作空间安全围栏的阻断策略，没有发给模型。原文不含策略名称或命中内容，按 `error.code` 判断策略类型：

| `error.code` | 命中的策略 |
| --- | --- |
| `guardrail_client` | 客户端访问控制：按来源 IP、工具名或 User-Agent 限制调用 |
| `guardrail_context` | 意图安全检测：请求意图被判定有风险 |
| `guardrail_sensitive` | 敏感信息检测：请求含个人信息、凭证或敏感关键词 |
| `guardrail_injection` | 提示词注入检测：请求疑似提示词注入 |
| `guardrail_model` | 模型访问控制：所选模型不在允许范围内，对虚拟模型按实际选中的模型检查 |

- **`Response blocked by guardrail policy`**（`guardrail_sensitive`）：非流式请求的回答命中了敏感信息策略。上游已经生成回答，这次调用照常计费；流式请求已开始输出，不会中断，命中的内容打码后输出。
- **`Subject is blocked by an active security ban`**（`guardrail_subject_banned`）：意图安全检测策略的动作设为封禁，命中后触发它的 Key 被封禁，期间所有请求都被拒绝。到达策略设置的自动解封时间后解除，或由管理员在 **安全事件** 中提前解除。

同样的请求重试会得到同样的结果。调用方可以调整请求内容或换用允许的模型；管理员在 **安全事件** 查看命中详情，在 **安全围栏** 调整策略，见[安全围栏与语义审计](https://platform.lyrouter.com/ai_gateway/docs/guardrails)。

## 404 / 409：路径与资源不存在

| 状态码 | 报错原文 | `error.code` | 含义与处理 |
| --- | --- | --- | --- |
| 404 | `404 Route Not Found`（响应体为 `{"error_msg": ...}`） | — | 网关没有这个路径，或该路径不接受这个 HTTP 方法。常见原因是 Base URL 多写或少写了 `/v1`（OpenAI SDK 的 `base_url` 应为 `https://api.lyrouter.com/v1`，Anthropic SDK 为根地址），见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)。这类请求在日志中查不到 |
| 404 | `video task not found` | `not_found` | 视频任务 ID 不存在、已过期，或属于其他工作空间 |
| 409 | `video is not ready yet` | `not_ready` | 任务还没有成功完成，暂时不能下载视频。继续轮询任务状态 |
| 409 | `cancelling an in-flight video task is not supported: ...` | `cancel_not_supported` | 不能取消进行中的任务（上游不提供取消接口）。等任务结束后仍可删除 |

`POST /v1/responses` 中的 `previous_response_id` 由上游服务商校验，出错时返回上游的错误，见[Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api)。视频任务本身失败时，查询接口返回 HTTP 200，任务对象的 `status` 为 `failed`，`error.code` 为 `deadline_exceeded`（超时，目前查询接口可能看不到，见[异步任务](https://platform.lyrouter.com/ai_gateway/docs/async)）、`canceled`（已取消），或上游给出的错误码（缺省为 `upstream_error`），有时还带上游的请求 ID `error.provider_request_id`，见[异步任务](https://platform.lyrouter.com/ai_gateway/docs/async)。

## 429：限流、熔断与上游限额

| 报错原文 | `error.code` | 含义与处理 |
| --- | --- | --- |
| `rate limit exceeded on <对象> <指标>/<窗口>` | — | Key 的预算或安全围栏的配额策略已达上限，如 `rate limit exceeded on apikey total_tokens/day`。错误体带 `limit`、`used`、`reset_at`（配额策略还带 `policy_code`、`policy_name`）。等到 `reset_at` 之后再调用，或请管理员调高额度 |
| `API Key 因最近 60 秒错误率过高已临时熔断，请在 N 秒后重试。` | `api_key_circuit_open` | 这个 Key 最近 60 秒至少 100 次请求、其中 90% 以上失败，被临时熔断。响应头 `Retry-After` 给出等待秒数，错误体的 `retry_after`、`blocked_until`（UTC）与之一致。先修复失败原因再等待 |
| `all upstream credentials for this model are rate limited` | `upstream_quota_exhausted` | 能服务这个模型的所有上游通道或凭证都达到了各自的限额，错误体带 `metric`、`window`。稍后重试或换用其他模型；只走 BYOK 时请管理员检查凭证限额 |
| `upstream concurrency full` | `upstream_concurrency_full` | 异步任务提交（如 `POST /v1/videos`）时，上游账号的并发任务数已满，请求没有发出。稍后重试 |

- **配额字段**：`<对象>` 为 `apikey`、`member`、`dept`、`ws`；`<指标>` 为 `requests`、`total_tokens`、`prompt_tokens`、`completion_tokens`、`credits`；`<窗口>` 为 `minute`、`minutes`、`day`、`month`、`total`（累计，不会重置）。窗口按北京时间对齐，用量在请求完成后才计入。
- **响应头**：配置了配额时，对话、向量等经过网关选路和配额检查的调用（成功的响应和被配额拦下的 429 都算）都带 `x-aigw-quota-<指标>-limit` / `-remaining` / `-reset`，指标为 `credits`、`tokens`、`requests`、`input-tokens`、`output-tokens`；`/v1/messages` 另带 `anthropic-ratelimit-*`，但 Credits 没有对应的头，只配置了 Credits 配额时网关不生成 `anthropic-ratelimit-*`。
- **Retry-After**：只有熔断（`api_key_circuit_open`）设置，同时带 `X-RateLimit-Reason: api_key_circuit_open` 和 `X-RateLimit-Reset`（Unix 秒）；配额 429 不带。上游自己的 `Retry-After` 只在 `/v1/messages` 上转发。
- **熔断阶梯**：第 1 次 30 秒、第 2 次 2 分钟、第 3 次 10 分钟、第 4 次 12 小时，第 5 次永久封禁，次数在 Key 的整个生命周期内累计。网关返回的 402、403、429 也计为失败；被熔断的请求不写入日志。

完整说明见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)和[预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota)。

## 500 / 504：连接上游失败或等待超时

| 状态码 | 响应体 | 含义 |
| --- | --- | --- |
| 504 | HTML 错误页 | 等待上游响应超时，或连接上游超时 |
| 500 | HTML 错误页 | 连接上游失败（如连接被拒绝、TLS 握手失败），或读取上游响应时出错 |

- 网关等待上游的读超时为 6 分钟；流式请求按相邻两段输出的间隔计算，持续有输出就不会超时。
- 返回之前，网关已按[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)的规则尝试过其他通道，所有候选都失败后才返回。流式请求开始输出后不再换通道，见下文「流式输出中途的错误事件」。
- 处理：使用有上限的指数退避重试；生成很长的内容时改用 `stream: true`；在日志「各阶段耗时」中查看上游耗时，详见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors)。

### 配置类 500（JSON 错误体）

以下 500 带 JSON 错误体（`type` 为 `api_error`），表示平台侧的通道或格式转换配置有问题，与请求内容无关，重试通常无效。请记下 Request ID 联系支持，并换用其他模型：

| `error.code` | 报错原文 |
| --- | --- |
| `model_unresolved` | `sync spec needs the upstream model name for the path` |
| `spec_error` | `unusable sync body shape: <原因>`、`unusable async submit spec: <原因>` |
| `unsupported_configuration` | `remove_model is not supported on multipart endpoints` |
| `encode_failed` | `failed to encode request body: <原因>` |

## 503：无可用通道、计费或配置暂不可用

| 报错原文 | `error.code` | 含义与处理 |
| --- | --- | --- |
| `all routed candidates exhausted` | `no_route_candidate` | 找不到任何可以服务这次请求的模型或通道。常见原因是 `@vmodel/<名称>` 写错、虚拟模型不存在或已停用，或模型没有可用的通道。检查 `model` 字段；名称无误时请管理员检查 **模型广场** 和 **自带密钥（BYOK）** |
| `No configured credential can serve this model` | `no_route_candidate` | 模型的通道在本工作空间没有可用凭证：平台通道没有开通，或 BYOK 凭证都不可用，见 [BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok) |
| `Workspace model projection is unavailable` | `workspace_model_projection_unavailable` | 网关暂时读不到工作空间的模型配置，属于平台侧问题，稍后重试 |
| `Platform supplier cost snapshot is unavailable`、`BYOK supplier cost snapshot is unavailable` | `supplier_cost_snapshot_not_ready` | 能服务这个模型的通道还没有配置好价格，网关无法计费。网关会先尝试其他通道，都不可用时才返回。换用其他模型，并把模型 ID 告知支持人员 |
| `billing balance is temporarily unavailable` | 见下表 | 网关暂时无法确认账户余额，为避免错误扣费而拒绝调用。这不是余额不足 |

`billing balance is temporarily unavailable` 的 `type` 为 `billing_unavailable`，按 `error.code` 判断能否自行恢复：

| `error.code` | 含义 | 重试是否有用 |
| --- | --- | --- |
| `billing_maintenance` | 账户计费正处于核对或维护状态，该账户下所有调用都被拒绝 | 无用，联系支持 |
| `billing_store_error`、`billing_store_protocol_error`、`byok_release_failed` | 平台计费服务临时故障 | 稍后可能恢复 |
| `invalid_balance`、`byok_billing_config_missing`、`byok_reservation_terminal` | 平台侧计费数据或配置异常 | 无用，联系支持 |

OpenAI、Anthropic 等官方 SDK 默认会自动重试 503，但 `no_route_candidate`、`billing_maintenance`、`supplier_cost_snapshot_not_ready` 不改请求或配置就不会恢复。

## 上游服务商返回的错误

网关把上游服务商返回的错误状态码和响应体**原样**转发给你，日志「状态说明」列的来源显示为「上游」。

- **先换通道**：上游返回错误或连接失败时，网关按工作空间的选路策略在同一模型的其他通道上重试，全部失败时你收到**最后一次**尝试的上游错误。设置了默认模型时，对话请求还可能改由默认模型回答，见[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。
- **上游 401 / 403**：通常是上游凭证被拒绝。使用 BYOK 时，请在服务商处确认 API Key 有效、额度充足，并在 BYOK 中重新测试连接。
- **`/v1/messages`**：上游错误同样转换为 Anthropic 格式。

### 上游返回空响应体

上游只返回错误状态码、没有响应体时，网关补一个错误体，并用 `generated_by: "ai-gateway"` 标明由网关生成：

```json
{
  "error": {
    "message": "upstream <服务商> returned HTTP 429 for POST <路径> with an empty response body",
    "type": "rate_limit_error",
    "code": "upstream_rate_limited",
    "upstream_status": 429,
    "generated_by": "ai-gateway"
  }
}
```

| 上游状态码 | `error.code` |
| --- | --- |
| 400 | `upstream_invalid_request` |
| 401 | `upstream_unauthorized` |
| 403 | `upstream_forbidden` |
| 404 | `upstream_not_found` |
| 408 | `upstream_timeout` |
| 413 | `upstream_payload_too_large` |
| 429 | `upstream_rate_limited` |
| 其他 4xx、5xx | `upstream_error` |

上游在响应头中带了自己的请求 ID 时，错误体还会多一个 `upstream_request_id`，向服务商报障时用它。

### 上游在成功响应里声明了错误

个别上游会返回 HTTP 2xx、却在响应体里声明失败，多见于图像、视频生成。网关把它改写为错误响应，状态码取上游声明的错误，`error.code` 为 `upstream_rejected`（上游拒绝了请求）或 `upstream_no_artifact`（上游没有产出图像或视频，带 `upstream_finish_reason`），`upstream_status` 是上游原本的 2xx 状态码。这类错误不换通道重试，请按 `error.message` 调整请求内容。

## 流式输出中途的错误事件

上面列出的网关拒绝都发生在开始输出之前，`stream: true` 的请求同样收到普通的错误响应和对应状态码，而不是 SSE 事件。

流式输出开始后（状态码已经是 200），上游中断或超时时，网关不再换通道，而是在流的末尾补一个错误事件，然后结束连接：

**OpenAI 兼容接口**（Chat Completions、Responses 等）：

```text
data: {"error": {"message": "upstream timed out after the response had started", "type": "api_error", "code": "stream_interrupted"}}
```

**Anthropic Messages**（`/v1/messages`）：

```text
event: error
data: {"type": "error", "error": {"type": "api_error", "message": "upstream timed out after the response had started"}}
```

- 超时时 `message` 为 `upstream timed out after the response had started`，连接或读取失败时为 `upstream failed after the response had started`。
- 上游自己在流中发出的错误事件（如 Anthropic 的 `overloaded_error`）按你调用的协议转给你。OpenAI、Anthropic 官方 SDK 收到这两种错误事件都会抛出 API 错误。
- 出现错误事件时不会再有结束标记（`data: [DONE]`、`message_stop`、`response.completed`）。请把「没有收到结束标记」当作这次调用失败，不要把已收到的部分输出当作完整结果。

各协议的事件结构见[流式响应](https://platform.lyrouter.com/ai_gateway/docs/streaming)，重试与去重建议见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors)。

## 哪些错误可以重试

| 处理方式 | 错误 |
| --- | --- |
| 有上限的指数退避重试 | 500、504（HTML）；502 `failed to reach upstream`；401 `api key verification unavailable`；403 `api key workspace is unavailable`；429 `upstream_quota_exhausted`、`upstream_concurrency_full`；503 `workspace_model_projection_unavailable`、`billing_store_error` 类；流式 `stream_interrupted` |
| 按指定时间等待 | 429 `api_key_circuit_open`：等 `Retry-After` 秒；配额 429：等到 `reset_at` 之后 |
| 修改请求或配置后再调用 | 全部 400、401 `missing credentials` / `invalid authorization scheme` / `invalid api key`、402、大部分 403、404、409；503 `no_route_candidate`、`supplier_cost_snapshot_not_ready`、`billing_maintenance`；配置类 500 |

不要对 4xx 做无间隔的自动重试：网关返回的 402、403、429 都计入错误率熔断，持续失败的程序很快会让 Key 被熔断，第 5 次熔断即永久封禁。

## 请求标识

### 网关不返回请求 ID

LYRouter 不在响应头里返回请求 ID。响应体中的 `id`（如 `chatcmpl-...`、`msg_...`、`resp_...`）是协议对象的 ID，不能在日志中按它查找。要定位某次调用，请在客户端记下调用时间、接口路径、模型和 API Key 名称，再到日志中找到这次请求。

### 从日志详情取 Request ID

1. 在工作空间左侧菜单打开 **日志分析**。日志在调用结束后几秒内可以查到。
2. 用「时间范围」「API Key」「模型」「状态码」等条件筛选。列表的「时间」是请求结束的时间。
3. 点击这一行打开「日志详情」，顶部「Request ID」后面就是这次请求的标识，选中后复制。

Request ID 可以粘贴到日志搜索框中重新找到这条日志。普通成员只能看到自己创建的 API Key 产生的日志。以下请求在日志中查不到：401、路径不存在的 404、被错误率熔断（429 `api_key_circuit_open`）或永久封禁（403 `api_key_permanently_banned`）拒绝的请求，以及 `GET /v1/models`。这些情况请提供调用时间、接口路径和完整报错。日志的完整用法见[通过日志定位调用问题](https://platform.lyrouter.com/ai_gateway/docs/logs)。

### 日志中的其他标识

| 标识 | 在哪里看 | 用途 |
| --- | --- | --- |
| Request ID | 日志详情顶部 | 唯一标识一次请求，联系支持时提供 |
| 会话 ID | 列表「会话」列的标签（在 **自定义列** 中打开），鼠标停留可见；「添加筛选」中可按「会话 ID」筛选 | 查看同一段对话的全部请求。客户端可用 `x-session-id` 请求头声明会话 |
| 任务 ID | `POST /v1/videos` 返回的 `id`（`aigwt_` 开头）；异步任务日志详情切换到「整个任务」 | 查询任务状态与产物，排查异步任务 |
| 上游请求 ID | 日志详情「原始报文」中「③ 上游响应」的响应头（各服务商头名不同，如 `x-request-id`）；空响应体补全错误的 `upstream_request_id`；失败视频任务的 `error.provider_request_id` | 向上游服务商报障，使用 BYOK 时联系你自己的服务商 |

### 提交问题时附上什么

| 信息 | 说明 |
| --- | --- |
| Request ID | 日志中能找到这次请求时附上 |
| 调用时间 | 精确到分钟，注明时区 |
| 接口与模型 | 方法和路径（如 `POST /v1/chat/completions`）、请求中的 `model`、是否流式 |
| 完整报错 | HTTP 状态码和完整响应体（含 `error.code` 和附加字段）；流式中断时附最后收到的几个事件 |
| API Key 名称 | 只提供名称 |
| 客户端 | 工具或 SDK 的名称与版本；超时问题附客户端的超时设置；IP 白名单问题附出口 IP |
| 相关标识 | 任务 ID、会话 ID、上游请求 ID（有的话） |

发送前请脱敏：

- 不要发送 API Key 明文、完整的 `Authorization` 或 `x-api-key` 请求头，以及你在服务商处的 BYOK 密钥。
- 提示词、回答和上传文件中的个人信息、业务数据先删除或替换；能用最小的复现内容说明问题时，不要附原文。
- 从日志「原始报文」复制的内容不含凭据类请求头，但正文可能包含敏感信息，发送前请检查。