01 / CONFIGURATION
先排除 Base URL 和密钥混用
若客户端或 SDK 要求填写基础地址，使用 https://openrouter.ai/api/v1；直接发送聊天补全 HTTP 请求时，完整地址是 https://openrouter.ai/api/v1/chat/completions。具体字段以客户端说明为准。
- 查看客户端最终请求地址，确认没有重复的
/v1或/chat/completions。只查看设置框可能看不出重复拼接。 - 确认密钥来自 OpenRouter，发送请求时使用 Bearer 鉴权。其他 API 平台即使协议兼容，其密钥和余额也不互通。
- 从当前官方模型页复制完整模型 ID，不用模型家族名替代，不保留示例占位符。
- 退回最小文本请求，先去掉图片、工具和不必要的参数，再逐项加回。参见 可运行的请求模板。
02 / STATUS
按状态码定位下一步
以下是排查顺序，不是仅凭状态码就能确定的唯一原因。保留脱敏后的错误正文，尤其是 error.message 和提供商返回的说明。
401：密钥或鉴权失败
检查密钥是否缺失、已撤销、复制不完整，或来自其他平台。确认 Authorization 使用 Bearer 格式。修正鉴权再请求，不要通过高频重试解决。
402：余额或消费上限不足
检查 OpenRouter 账户余额、单个密钥的消费上限和实际模型。其他产品的聊天会员不等于这里的 API 额度；免费模型也可能受账户状态影响，见 免费额度查询。
403：权限、审核或安全规则
阅读返回的拦截原因，检查账户权限和适用的审核、guardrail 规则。不要把它简单当作余额不足，也不要尝试绕过服务的安全限制。
404：路径或资源不存在
核对完整请求 URL、模型 ID 与当前目录。不要只改域名而保留另一平台的接口路径。资源确实不存在时，应先修正目标，而不是原样重试。
429：请求受限
既可能是平台配额或频率限制，也可能来自上游提供商。降低并发，核对每日免费请求剩余量；存在 Retry-After 时遵循其等待要求。新增密钥不能扩大平台账户限额。
502 / 503：模型或提供商暂不可用
502 可能涉及模型不可用或上游响应异常；503 可能是没有满足路由条件的可用提供商，或上游过载。检查模型支持的能力、提供商条件与当前可用性。不要为了请求成功就放宽组织要求的数据隐私设置。
400 等参数问题可先检查 JSON 格式、必填字段、上下文和模型支持的参数。完整错误定义见 OpenRouter 官方错误文档。
03 / RESPONSE
HTTP 200，为什么还是没有回复？
HTTP 200 不足以证明模型完整回答成功。还应检查响应体和请求是否使用流式输出：
- 非流式：检查顶层
error、choices[].error、结束原因和实际内容。普通文本补全常从choices[0].message.content读取，但工具调用等输出不一定是文本。 - 流式：连接建立后仍可能收到 SSE 错误或
finish_reason: "error"。要解析完整事件流，不要把收到第一块数据当作成功结束。 - 客户端显示空白：对照原始响应检查解析方式。不要把 SSE 当普通 JSON 一次读取，也不要只检查 HTTP 状态。
在 Node.js 入门示例中已经加入了响应错误检查；它演示的是非流式、普通文本请求，不是完整的流式客户端。
04 / RETRY
哪些情况应该等，哪些应该先改？
| 问题 | 下一步 |
|---|---|
| 地址、鉴权、权限、余额 | 先修正配置或账户状态。保持原样的快速重试通常不会解决问题。 |
| 频率或容量限制 | 遵循存在的 Retry-After；降低并发、延迟后有限重试，并设置最大次数和超时。 |
| 无匹配提供商 | 检查能力和路由条件。确需切换模型或服务时，重新确认价格、数据规则及业务授权。 |
| 超时或结果不确定 | 不要假定服务器没有处理请求。重复请求可能产生额外用量；有工具副作用的业务还需避免重复执行。 |
重试策略应按业务实现，本文不自动发送请求、不提供在线密钥检测，也没有进行真实 API 调用。
05 / SUPPORT
求助时提供什么，不提供什么？
- 提供：发生时间与时区、完整模型 ID、客户端及版本、是否流式、HTTP 状态、脱敏错误正文，以及响应中已有的请求标识。
- 删除：Authorization、API Key、Cookie、私人对话、个人信息和不应公开的业务数据。
- 说明：最小请求是否也失败，是否只影响某个模型，以及重试前做过哪些检查。
账户和付款问题应提交给实际服务商的官方支持。本站不能查看、恢复或调整你的密钥和余额。
资料与下一步
依据 Quickstart、Errors and Debugging 与 Limits整理；检查顺序为本站的实用整理，不代表官方支持结论。