Errors and Debugging

API 错误和调试

原文链接：https://openrouter.ai/docs/api/reference/errors-and-debugging

对于错误，OpenRouter 返回具有以下形状的 JSON 响应：

type ErrorResponse = {
  error: {
    code: number;
    message: string;
    metadata?: Record<string, unknown>;
  };
};

HTTP 响应将具有与 error.code 相同的状态代码，如果：

你的原始请求无效
你的 API key/账户积分不足

否则，返回的 HTTP 响应状态将为 200，LLM 生成输出时发生的任何错误都将在响应体中或作为 SSE 数据事件发出。

错误代码

400：Bad Request（无效或缺少参数、CORS）
401：Invalid credentials（OAuth 会话过期、禁用/无效 API key）
402：你的账户或 API key 积分不足。添加更多积分并重试请求。
403：Forbidden（权限不足、guardrail 阻止或审核标记）
408：你的请求超时
429：你正受到速率限制
502：你选择的模型宕机或我们收到无效响应
503：没有满足你路由要求的可用模型 provider

Retry-After Header

在 429 和 503 响应上，OpenRouter 可能包含标准 HTTP Retry-After 响应头，指示重试前应等待的秒数。

OpenAI SDK、Anthropic SDK、Vercel AI SDK 和 OpenRouter SDK 已经尊重此 header 进行退避。如果你直接使用 fetch，在重试之前遵守它。

审核错误

如果你的输入被标记，error.metadata 将包含有关问题的信息。metadata 的形状如下：

type ModerationErrorMetadata = {
  reasons: string[]; // 你的输入被标记的原因
  flagged_input: string; // 被标记的文本片段，限制为 100 个字符
  provider_name: string; // 请求审核的 provider 名称
  model_slug: string;
};

Guardrail 错误

在推理 endpoints（/chat/completions、/responses、/messages）上，请求可以在到达 provider 之前被阻止——例如，被通过 guardrails 配置的内容过滤器或 prompt-injection 检测器阻止。当这种情况发生时，响应是一个 403，消息描述了阻止原因。

当你通过 X-OpenRouter-Experimental-Metadata: enabled header 选择加入 router metadata 时，403 响应还包括完整的 openrouter_metadata 对象，其中包含路由上下文和 pipeline 数组，详细说明运行的 guardrail stages。

Provider 错误

如果模型 provider 遇到错误，error.metadata 将包含有关问题的信息。metadata 的形状如下：

type ProviderErrorMetadata = {
  provider_name: string; // 遇到错误的 provider 名称
  raw: unknown; // 来自 provider 的原始错误
};

当没有生成内容时

偶尔，模型可能不会生成任何内容。这通常发生在：

模型从冷启动升温
系统正在扩展以处理更多请求

预热时间通常从几秒到几分钟不等，取决于模型和 provider。

如果你遇到持续的无内容问题，请考虑实施简单的重试机制或尝试使用不同 provider 或最近活动更多的模型。

另外，请注意，在某些情况下，你可能仍会被上游 provider 收取 prompt 处理费用，即使没有生成内容。

流式错误格式

使用流式模式（stream: true）时，错误根据发生的时间以不同方式处理：

流前错误

在任何 tokens 发送之前发生的错误遵循上述标准错误格式，并带有适当的 HTTP 状态代码。

流中错误

在流式传输开始后发生的错误作为 Server-Sent Events (SSE) 发送，具有统一结构，包括错误详情和完成选择。

关键特征：

错误出现在顶层，与标准响应字段并列
包含 choices 数组和 finish_reason: "error" 以正确终止流
HTTP 状态保持 200 OK，因为 headers 已经发送
流在此事件后终止

OpenAI Responses API 错误事件

OpenAI Responses API (/api/v1/responses) 对流式错误使用特定的事件类型：

错误事件类型：

response.failed - 官方失败事件
response.error - 响应生成期间的错误
error - 普通错误事件

错误代码转换

Responses API 将某些错误代码转换为具有特定完成原因的成功完成：

错误代码	转换为	完成原因
`context_length_exceeded`	Success	`length`
`max_tokens_exceeded`	Success	`length`
`token_limit_exceeded`	Success	`length`
`string_too_long`	Success	`length`

这允许对基于限制的错误进行优雅处理，而不是将它们视为失败。

调试

OpenRouter 提供了一个 debug 选项，允许你检查发送到上游 provider 的确切请求体。这对于了解 OpenRouter 如何转换你的请求参数以与不同 providers 配合使用很有用。

调试选项形状

调试选项是一个具有以下形状的对象：

type DebugOptions = {
  echo_upstream_body?: boolean; // 如果为 true，则返回发送到 provider 的转换后的请求体
};

使用

要启用调试输出，请在请求中包含 debug 参数：

fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'anthropic/claude-haiku-4.5',
    stream: true, // Debug 仅适用于流式
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Hello!' },
    ],
    debug: {
      echo_upstream_body: true,
    },
  }),
});

调试响应格式

当 debug.echo_upstream_body 设置为 true 时，OpenRouter 将发送调试 chunk 作为流式响应中的第一个 chunk。

重要说明

仅适用于流式 Chat Completions：调试选项仅适用于 Chat Completions API 的流式模式（stream: true）。非流式请求和 Responses API 请求将忽略调试参数。

不适用于生产：调试标志不应在生产环境中使用。它仅用于开发和调试目的，因为它可能潜在地返回包含在请求中的敏感信息，这些信息本不应在别处可见。