OpenRouter Responses API Beta 使用统一的 JSON 错误格式，所有错误都包含 error.code 和 error.message 两个字段。目前有三种错误码：请求校验失败（400）、超过频率限制（429）、服务端内部错误（500+）。由于 API 是无状态的，每次请求失败后需要携带完整对话历史重新发起请求。本页提供错误格式说明和各错误码的处理建议。

Beta API：该 API 处于 beta 阶段，可能存在破坏性变更，生产环境请谨慎使用。

无状态设计：该 API 是无状态的——每次请求相互独立，服务端不保存对话状态。失败后重试需要重新传入完整对话历史。

Responses API Beta 返回统一格式的结构化错误响应。

错误响应格式

所有错误均遵循以下结构：

{
  "error": {
    "code": "invalid_prompt",
    "message": "Detailed error description"
  },
  "metadata": null
}

错误码

错误码	说明	对应 HTTP 状态码
invalid_prompt	请求校验失败	400
rate_limit_exceeded	请求过于频繁	429
server_error	服务端内部错误	500+

错误处理示例

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/o4-mini',
    input: 'Hello',
    max_output_tokens: 9000,
  }),
});

const result = await response.json();

if (result.error) {
  switch (result.error.code) {
    case 'invalid_prompt':
      console.error('请求参数错误:', result.error.message);
      break;
    case 'rate_limit_exceeded':
      console.error('超过频率限制，请稍后重试');
      break;
    case 'server_error':
      console.error('服务端错误，请稍后重试:', result.error.message);
      break;
    default:
      console.error('未知错误:', result.error);
  }
} else {
  // 处理正常响应
  console.log(result.output);
}

各错误码处理建议

invalid_prompt（400）：检查请求体格式，确认 model、input 等必填字段是否正确，结构化消息数组中 type、role 等字段是否符合规范。

rate_limit_exceeded（429）：实现指数退避重试，避免立即重试加重压力。可参考响应头中的 Retry-After 字段（如果存在）。

server_error（500+）：属于服务端问题，稍后重试即可。如果持续出现，可查看 OpenRouter 状态页或联系支持。

常见问题

Q: 错误响应中 metadata 字段为什么是 null？

A: metadata 字段目前固定为 null，是 API 响应格式的占位字段，未来可能包含更多错误上下文信息。

Q: 如何区分客户端错误和服务端错误？

A: 通过 HTTP 状态码区分：400 系列（如 400、429）是客户端问题，需要修改请求后重试；500 系列是服务端问题，等待后重试即可。

Q: Beta 阶段是否可能新增错误码？

A: 是的。由于 API 处于 beta 阶段，错误码可能随版本更新而变化。建议在错误处理代码中添加兜底 case 处理未知错误码。