OpenRouter API 返回统一格式的错误响应，包含 code、message 和可选的 metadata 字段。本页涵盖所有 HTTP 错误码的含义（400~503）、审核错误和提供商错误的 metadata 结构、流式传输中两种不同时机的错误处理方式，以及仅限开发环境的 debug 选项——可查看请求被转换后实际发送给上游提供商的内容。

OpenRouter API 错误处理与调试

错误响应格式

所有错误都返回以下 JSON 结构：

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

HTTP 响应状态码与 error.code 一致，以下情况会返回错误状态码：

• 请求参数无效
• API key 或账户余额不足

其他情况下，HTTP 状态码为 200——LLM 生成过程中发生的错误会在响应体或 SSE 事件中返回。

HTTP 错误码说明

状态码	含义
400	Bad Request：参数无效或缺失、CORS 问题
401	认证失败：OAuth 会话过期、API key 被禁用或无效
402	余额不足：账户或 API key 信用额度用完，充值后重试
403	内容被审核：所选模型需要内容审核，你的输入被标记
408	请求超时
429	速率限制：请求过于频繁
502	上游错误：所选模型不可用或返回了无效响应
503	无可用提供商：没有满足你的路由要求的提供商

审核错误（403）

输入被标记时，error.metadata 包含详细信息：

type ModerationErrorMetadata = {
  reasons: string[];        // 被标记的原因
  flagged_input: string;    // 被标记的文本片段（最多 100 字符）
  provider_name: string;    // 发起审核的提供商名称
  model_slug: string;
};

提供商错误（502）

提供商出错时，error.metadata 包含：

type ProviderErrorMetadata = {
  provider_name: string; // 出错的提供商名称
  raw: unknown;          // 提供商返回的原始错误
};

流式传输错误处理

流式传输（stream: true）中，错误处理方式取决于发生时机：

首个 token 前发生的错误

返回标准 JSON 错误响应，带对应 HTTP 状态码。

已发送部分 token 后发生的错误

由于 HTTP 状态码已发出（200 OK），错误以 SSE 事件形式返回，结构如下：

type MidStreamError = {
  id: string;
  object: 'chat.completion.chunk';
  created: number;
  model: string;
  provider: string;
  error: {
    code: string | number;
    message: string;
  };
  choices: [{
    index: 0;
    delta: { content: '' };
    finish_reason: 'error';
    native_finish_reason?: string;
  }];
};

处理两种错误的完整示例：

const request = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  // ...
});
console.log(request.status); // 非流式错误会在这里体现
const response = await request.json();
console.error(response.error?.status);
console.error(response.error?.message);

Debug 选项

在请求体中传入 debug 参数，可查看 OpenRouter 实际发送给上游提供商的请求体：

{
  "model": "anthropic/claude-haiku-4.5",
  "stream": true,
  "messages": [...],
  "debug": {
    "echo_upstream_body": true
  }
}

Debug 信息作为第一个流式 chunk 返回，choices 为空数组，debug 字段包含转换后的请求体。

重要限制：

• 只对流式请求（stream: true）有效
• 不要在生产环境使用，可能返回敏感信息
• 当使用多提供商 fallback 时，每次尝试都会发送一个 debug chunk

Debug 实用场景

1. 理解参数转换：查看 max_tokens、temperature 等参数如何映射到各提供商的格式
2. 验证消息格式：检查消息合并和格式化方式
3. 排查默认值：查看 OpenRouter 自动填充了哪些默认参数
4. 调试 Fallback：追踪每个尝试的提供商及其请求参数

---

常见问题

Q: 返回 503 是什么意思？如何处理？

A: 没有满足路由要求的可用提供商。可以放宽 provider 参数限制（如允许 fallback），或切换到更多提供商支持的模型。

Q: 流式传输时，怎么知道是中途出错还是正常完成？

A: 检查每个 chunk 是否包含顶层 error 字段。正常完成时 finish_reason 为 stop 或 length，出错时为 error。

Q: 402 错误出现了，充值后需要重新发请求吗？

A: 是的，充值后重新发送请求即可。余额恢复后会立即生效。