根据 API 错误继续处理

看到报错时，先别乱试。先记下 HTTP 状态码和一条不含敏感信息的错误消息，再一次只改一个地方。

先按状态码找方向

你看到的结果	先检查	第一个动作
400 Bad Request	JSON、必填字段、请求格式	从最小示例重新对照 model 和 messages
401 Unauthorized	Token 和认证头	重新复制 Token，确认使用 Authorization: Bearer
403 Forbidden	Token 权限或账户可用范围	用同一 Token 重新列出 /v1/models
404 Not Found	Base URL 和端点拼接	检查是否重复或遗漏 /v1、/chat/completions
429 Too Many Requests	Token 额度、账户余额或请求频率	在门户查看当前状态，等待后降低并发或更换有效额度
5xx	服务暂时无法完成请求	保留请求时间和状态码，稍后重试一次
超时或无法连接	地址、DNS、代理、证书和网络	先请求 https://api.zhiflo.com/v1/models，缩小问题范围

如果模型不存在或不可用

这类错误不一定对应固定状态码。先用相同 Token 调用 GET /v1/models，复制响应中 data[].id 的完整值，再替换请求中的 model。

不要从搜索结果复制一个看起来相似的模型名。大小写、斜杠、连字符和后缀都必须保持一致。

如果你遇到 404

客户端要求 Base URL 时，通常填写：

https://api.zhiflo.com/v1

客户端会自己追加 /chat/completions 或 /responses。如果字段明确要求完整 Chat Completions endpoint，才填写：

https://api.zhiflo.com/v1/chat/completions

Claude Code 是例外：ANTHROPIC_BASE_URL 使用 https://api.zhiflo.com，由客户端追加 /v1/messages。

如果列模型成功，但真正生成失败

这说明地址和 Token 的基础认证已通过。下一步只核对：

1. 请求中的模型 ID 是否来自刚才的响应；
2. 客户端选择的协议是否与请求路径一致；
3. POST 正文是否为有效 JSON，并包含所用接口需要的字段；
4. Token 额度和账户状态是否允许本次请求。

记录哪些信息是安全的

排错时可以记录：请求时间、HTTP 方法、路径、状态码、请求 ID、客户端名称和已遮罩的配置。不要发送完整 Token、完整私人对话、未脱敏截图或包含凭据的配置文件。

下一步：如果不是明确的 HTTP 错误，使用 连接故障排查 按层定位。