常见问题与错误排查
先判断请求进行到哪一步
- 没有收到 HTTP 响应：DNS 解析、TLS 证书、连接失败或超时，先检查完整地址和运行环境的网络。不要通过关闭证书校验来跳过问题。
- 收到 HTTP 错误码：同时读取 JSON 中的
error.message、message或其他具体错误文字，再对照下表处理。 - HTTP 200 但没有预期结果：检查响应正文、流式格式和任务状态。异步任务提交成功不表示生成完成。
状态码怎么处理
| 状态 | 优先检查 | 下一步 |
|---|---|---|
| 400 | JSON、必填参数、模型参数和协议 | 从最小请求重新测试，移除暂时不用的高级参数 |
| 401 | 完整 API Key、启用状态、有效期、认证头 | 从API 密钥页面重新复制，避免复制打码内容或重复 sk- |
| 403 | 模型权限、分组、IP 白名单 | 核对密钥限制；白名单填写的是实际发起请求的服务器出口 IP |
| 404 | 请求路径、模型 ID 或任务 ID | 检查是否重复 /v1；不要只凭 404 断定是地址错误 |
| 408 / 超时 | 网络、客户端等待时间、服务端是否已经接收 | 查看使用日志；异步任务已有 ID 时先查询，不立即重复提交 |
| 429 | 限流或错误正文提示的额度约束 | 降低并发、延迟重试；需要额度时同时检查账号余额与密钥额度 |
| 500 / 502 / 503 / 504 | 服务端或上游状态 | 保留请求 ID 和错误内容，避免高频重试；持续失败时联系支持 |
实际错误含义以响应正文为准，同一种业务问题可能由不同接口返回不同状态码。
显示模型不存在，但目录里能看到
核对完整模型 ID、账号分组与密钥模型限制；确认客户端使用的是该模型支持的协议。能读取 /v1/models 不代表该模型能用于所有端点或所有工具。
充值后仍提示额度不足
账号余额和 API Key 的独立额度分别生效。余额已到账时，再检查该密钥是否耗尽额度、过期或被停用。若使用套餐，还需确认当前调用符合套餐范围。
返回 HTML 页面
通常请求进入了网页入口或不正确的路径。对照地址说明检查最终请求 URL，不把文档站地址作为 API 地址。
本机能调用，Dify 或 n8n 却不能
请求由 Dify/n8n 所在的服务器或容器发出。检查那个运行环境的 DNS、网络和代理；它的 localhost 指向它自己，不是你电脑上的 API 服务。
向支持提供什么
通过 CertaEdge 在线客服提供发生时间、客户端名称和版本、模型 ID、完整端点、HTTP 状态、脱敏错误正文，以及可用的请求 ID 或任务 ID。不要发送完整密钥、登录凭证或含敏感内容的完整对话。