← 返回文档首页

FAQ 与排障

API 错误码与排障

本页说明调用失败时客户可以自行判断和处理的步骤。HTTP 状态码、响应里的 error / message / code / success，以及上游返回的具体文本都可能随接口变化；请以本次响应为准，不要把某一个上游错误码当成永久约定。

先按这个顺序判断

  1. 看 HTTP 状态码。客户端超时、连接被重置或 TLS/DNS 失败时，可能根本没有 HTTP 状态码。
  2. 看完整响应：error、message、code、success: false。流式请求可能先返回 HTTP 200，再在 SSE 里给出错误。
  3. 记下 request_id（响应头或响应体）。联系支持时这是最重要的定位号。
  4. 再打开使用日志。失败请求经常没有消耗记录，这不代表平台没收到请求。

使用日志为什么常常是空的

  • 消耗：只记录已经计费或完成结算的调用。客户端收到 401、403、504 等失败时，通常没有消耗行，也不会扣费。
  • 错误：只记录部分已经到达上游渠道的失败。此类型也可能是空的。
  • 退款：只在已经扣费后又退回时出现。
  • 因此：下游已经报错、使用日志却没有对应行，经常是正常现象。请以客户端拿到的状态码、错误正文和 request_id 为准。
  • 下列失败尤其容易没有使用日志：Key 无效、账号或 Key 被禁用、IP 限制、模型不在 Key 允许列表、余额不足、入口超时、客户端先断开。
  • 图片、视频等异步任务请查看任务日志，不要只看普通消耗日志。

HTTP 状态码

  • 400 请求无效：JSON、必填字段、协议或模型参数不正确。先改成短文本，关闭流式和附件后重试。如果提示模型未定价，换一个已定价的公开模型，或联系管理员完成定价。
  • 401 未授权：Key 缺失、复制不完整、多了空格或错误前缀、Key 已过期或已删除。请求头必须是 Authorization: Bearer <API Key>。不要把完整 Key 发到截图或工单。
  • 403 无权限或拒绝：不要只看数字，按错误正文区分：
  • 账号或 Key 被禁用：在控制台查看账号状态和 API Key 状态。
  • 额度不足 / insufficient quota：充值或等待套餐额度恢复后再调用。
  • 模型不在 Key 允许列表：换有权限的模型，或调整该 Key 的模型范围。
  • IP 不在允许列表：从允许的网络访问，或请管理员调整 Key 的 IP 限制。
  • 分组无权或分组已弃用：换可用分组，或请管理员开通。
  • 上游返回 403：账号和 Key 看起来正常时，仍可能因上游暂时拒绝而失败。保留 request_id，用短请求重试一次；连续失败再联系支持。
  • 404 接口或模型不存在：使用平台公开模型名，不要填上游内部名；检查客户端没有把 /v1 拼两次，也没有写错路径。
  • 408 请求超时：请求在限定时间内没有完成。缩短上下文、去掉附件，并检查客户端超时后只重试一次。
  • 413 请求体过大：减小上下文、图片、文件或视频输入。
  • 429 限流：停止并发重试，等待后再发一次短请求。检查 Key 或账号的速率、次数和并发限制。
  • 500 服务器内部错误：保留 request_id，用短请求重试一次。不要对同一失败请求无限重放。
  • 502 / 503 上游或渠道不可用：该模型暂时没有可用渠道，或上游无响应。等待后用短请求重试一次；若持续失败，联系支持。
  • 504 网关超时：请求在完成前被超时切断。可能是客户端超时更短、网络中断，或平台/上游处理时间过长。使用日志常常没有对应行。先把客户端超时调长，改用短非流式请求，去掉超大上下文和附件，不要立刻对同一长请求连打。

没有状态码，或 HTTP 200 仍失败

  • 连接被重置 / TLS / DNS 失败：先检查 Base URL 是否为 https://www.zltokens.com/v1，再换网络或关闭会缓冲响应的代理。
  • 客户端先超时：客户端超时短于实际处理时间，会在本地报 timeout。把客户端超时调到大于平台处理时间，并用短请求验证。
  • 流式 HTTP 200，随后 SSE 报错：按 SSE 里的 error 处理，不要当成成功。可先关闭 stream 验证模型和 Key。
  • 空响应：对比一次非流式短请求；检查代理是否截断响应。
  • 敏感词拦截：修改提示词后重试，不要反复提交同一段被拦截内容。
  • 异步图片/视频任务稍后失败：到任务日志查看任务状态和退款。

建议的自助步骤

  1. 用低成本文本模型发一句短文本，关闭流式、图片、文件和长上下文。
  2. 短请求成功后再逐步加回原来的参数。
  3. 同一失败不要高频重试，避免把限流和超时叠加。
  4. 仍失败时按下面清单联系支持。

联系支持前请准备

发生时间及时区、request_id、接口路径、平台公开模型名、客户端名称和版本、是否流式、HTTP 状态码（或写明“无状态码”）、已脱敏的错误正文。不要提供 API Key、密码、完整支付信息或不必要的提示词和业务数据。