错误码与请求标识

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

错误响应格式

OpenAI 兼容格式

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

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

Anthropic 格式（/v1/messages）

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

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

转换后不再带 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 错误体的响应

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

# -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":"你好"}]}'

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)

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));
}

速查表

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

400：请求格式或参数

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

模型字段与请求体

设置了默认模型时，不写 model 的对话请求会改由默认模型回答，不会收到 missing_model。默认模型的设置见通道选择与路由策略。

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

模型不支持该接口或输入

type 为 invalid_request_error，按 error.code 区分：

处理：在 模型广场 查看模型支持的接口与输入类型，换用支持的模型，见模型能力与兼容性。

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

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

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

各参数的取值范围见多模态能力。

原生直通无法满足

原文：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 …"}}；在其他接口上是一行纯文本。括号里是否决的原因：

目前 /v1/messages 没有开启请求侧原生直通，带这个请求头的请求会以 route_disabled 被拒绝。去掉这个请求头（或改为 prefer），请求即按正常的协议转换路径处理，见Anthropic Messages。

401：鉴权失败

401 的请求无法归属到任何工作空间，日志中查不到。各条原因的详细排查见401 / 403：鉴权与权限。

402：余额不足或订阅到期

type 为 insufficient_quota。余额检查发生在调用之前：余额大于 0 就能发起调用，一次调用可能把余额扣成负数，之后的调用才被拒绝。余额不足时网关不会改用其他通道或计费方式。计费规则见计费规则与信用点。

403：访问被拒绝

API 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。
• 工作空间设置了默认模型时，请求的模型未开通的对话请求通常改由默认模型回答，可在日志的「模型（实际）」中确认。详见模型不可用。

安全围栏

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

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

同样的请求重试会得到同样的结果。调用方可以调整请求内容或换用允许的模型；管理员在 安全事件 查看命中详情，在 安全围栏 调整策略，见安全围栏与语义审计。

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

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

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

• 配额字段：<对象> 为 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：限流与配额和预算、配额与限流。

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

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

配置类 500（JSON 错误体）

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

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

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

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

上游服务商返回的错误

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

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

上游返回空响应体

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

{
  "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"
  }
}

上游在响应头中带了自己的请求 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 等）：

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

Anthropic Messages（/v1/messages）：

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）。请把「没有收到结束标记」当作这次调用失败，不要把已收到的部分输出当作完整结果。

各协议的事件结构见流式响应，重试与去重建议见超时与流式中断。

哪些错误可以重试

不要对 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。这些情况请提供调用时间、接口路径和完整报错。日志的完整用法见通过日志定位调用问题。

日志中的其他标识

提交问题时附上什么

发送前请脱敏：

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