常见错误与恢复

先记录 HTTP 状态码和请求路径，再按类别处理。

401 未认证

Key 缺失、失效、复制不完整，或认证请求头不符合当前协议。

重新从密钥页复制 Key，去掉首尾空格，并核对 Bearer、x-api-key 或 x-goog-api-key。

当前 Key、账户状态或模型访问范围不允许这次请求。

确认 Key 仍可用，并在模型与价格页重新选择当前可访问的模型。

Base URL、协议路径或 HTTP 方法不匹配，客户端也可能重复追加 /v1。

对照协议页检查完整路径和方法；Base URL 只填写教程指定层级。

短时间请求过密，或当前可用额度不足。

降低并发，按递增间隔重试，并在主站确认账户状态后再继续。

上游或网关暂时无法完成请求。

保留请求时间和状态码，稍后重试；连续失败时先用 curl 最小请求排除客户端配置。

本地网络、代理或长连接在响应完成前断开。

确认域名可访问；流式请求使用退避重连，非幂等操作不要自动重复提交。

保留发生时间、协议、HTTP 方法、路径、状态码和已脱敏的响应片段。不要附上完整 Key。