错误码与排障

下面是常见错误码和报错提示的快速判断。遇到问题时，优先提供报错截图、request_id、模型、时间和使用的软件。

快速判断

可以按下面的顺序判断：

1. 看错误码：先区分请求参数、权限、限流、服务异常或网络超时。
2. 看 request_id：将它与发生时间和模型一起提供给 TkForA 维护人员，便于定位后台日志。
3. 按原因处理：分别尝试修正配置、压缩请求、等待后重试、切换稳定网络，或提交完整反馈信息。

类型	常见信号	优先检查
客户端或请求问题	400、401、404、413	参数、路径、凭据占位配置和请求体大小
限流或额度问题	429、usage limit	并发、额度、重试频率和当前模型分组
服务或路由问题	403、502、503	权限、可用渠道、服务状态和路由配置
网络或流式问题	stream、reset、GOAWAY	网络、代理节点、连接时长和请求大小
边缘网络超时	522、524、cf-ray	服务可达性、响应时长和网关配置
请求过重	payload too large、timeout	上下文、文件、图片和单次任务规模

400 / Bad Request

请求格式或参数有问题。

常见原因：JSON 格式错误、字段名写错、字段不支持、请求体没有完整传到服务端、客户端中途断开、请求体过大或上传太慢。

如果提示 Failed to read request body，一般是请求体没有完整传到服务端。常见原因是网络断流、代理不稳定、客户端中断、请求体过大或上传太慢。

401 / Unauthorized

API Key 错误、未携带 Key、Key 被禁用，或 Bearer 格式不正确。

请检查：

• 是否填入了正确的 API Key。
• 是否使用了正确的认证格式，例如 Authorization: Bearer YOUR_API_KEY。
• Key 是否已被禁用或过期。
• Base URL 是否填写正确。

403 / Forbidden

当前请求没有权限或被拒绝。

常见原因：账户余额不足、分组权限失效、内容审计命中、服务路由权限异常、可用服务容量不足、服务凭据失效，或 IP、地区被服务端拒绝。

如果之前可以使用，随后突然出现大量 403，优先检查账户状态、分组权限和服务路由状态。

404 / Not Found

请求路径写错，或请求的模型在当前分组中不存在。

常见原因：Base URL 填错、接口路径写错、模型名称写错，或当前分组不支持该模型。

413 / Payload Too Large

请求体太大。

常见原因：文字太多、图片太大、文件太大或上下文太长，超过当前域名、网关或模型限制。

解决办法：压缩提示词，删除无关历史，拆分文件，减少图片，降低单次请求量。遇到 too_big、payload too large 或 maximum context length 这类提示，也按请求体过大处理。

429 / Rate Limit

请求触发限流。

常见原因：并发过高、待处理请求过多、API Key 独立额度用完、服务额度打满、服务处于冷却状态，或客户端连续快速重试。

如果提示 API key 额度已用完，说明当前 API Key 的独立额度耗尽，不一定代表账户余额不足。

如果提示 The usage limit has been reached，一般表示服务额度达到限制，不代表客户余额已经耗尽。频繁出现时，说明当前模型分组的可用容量可能不足。

如果提示 Upstream rate limit exceeded. Please retry later.，说明服务链路中的上游触发限流，建议稍等后再试，或切换模型、分组。

流式断开 / Stream Error

如果出现下面这类报错，通常表示流式连接中途断开：

• stream disconnected before completion
• stream closed before response.completed
• responses stream error
• connection reset by peer
• context canceled
• client connection lost
• server sent GOAWAY
• http2: server sent GOAWAY
• stream ended before a terminal event

常见原因：客户端网络不稳定、代理节点切换、链路丢包、客户端主动取消、服务长时间无响应，或者大上下文导致连接持续时间过长。

建议：重启客户端，切换稳定网络节点，关闭不稳定代理，降低单次上下文，开启流式输出，并避免连续快速重试。

负载过高 / 请求太大

如果提示负载过高、服务繁忙、网关超时或请求超时，一般不是 Key 错，而是当前请求太重或链路太慢。

常见原因：上下文太长、文件太大、一次性输入太多、模型处理时间过长、连续重试过快，或服务当前压力较高。

建议：压缩上下文，删除无关历史，拆分任务，减少图片和大文件，开启流式输出，失败后等待 30 至 60 秒再重试。

500 / Server Error

服务内部错误。

可能是服务端临时异常，也可能是请求处理链路中的服务异常，需要结合 request_id 判断。偶发错误可以稍后重试；持续出现时，请提供 request_id、模型和发生时间，联系 TkForA 维护人员。

如果客户端的自动审核或本地扩展导致请求异常，请先暂时关闭相关扩展，恢复为最小配置后重试，再逐项恢复设置以定位冲突项。

502 / Bad Gateway

服务、代理或网关返回异常。

常见原因：可用服务容量不足、模型上下文超限、参数不支持、代理断流、服务返回无效响应，或后端临时异常。

如果之前正常，随后突然出现大量 502，优先检查可用服务路由、网络节点和后端服务状态。

503 / Service Unavailable

当前服务不可用。

常见原因：当前分组没有可用服务容量、服务暂时不可调度、服务繁忙、路由器找不到可用渠道，或分组只允许特定客户端配置。

如果提示 no available accounts、no auth available 或 model channel not available，通常表示对应模型分组当前没有可调度容量。

504 / Gateway Timeout

网关等待服务响应超时。

常见原因：模型响应太慢、上下文过大、服务处理卡住，或代理链路延迟较高。

建议减少上下文、开启流式输出，稍后再试。

522 / Cloudflare Connection Timeout

Cloudflare 无法连接到服务。

常见原因：服务不可用、防火墙拦截、端口不可达，或服务器过载导致无法建立连接。

这是边缘网络到服务之间的连接问题，通常不是客户 Key 填写错误。

524 / Cloudflare Timeout

Cloudflare 已经连接到服务，但服务在规定时间内没有返回响应。

常见原因：请求持续时间过长、上下文过大、使用非流式请求、服务响应慢，或代理链路处理不过来。

如果长上下文或大任务频繁出现 524，建议开启流式输出、压缩上下文、拆分任务，或使用响应更快的服务路由。

Cloudflare 相关错误

如果错误信息中带有 cf-ray，说明请求经过了 Cloudflare。常见判断如下：

• 522：Cloudflare 无法连接到服务。
• 524：Cloudflare 已连接服务，但服务响应时间过长。
• 413：请求体超过限制。
• 429：Cloudflare、TkForA 或请求链路中的其他服务触发限流。

排查时应同时记录 cf-ray、request_id、发生时间和请求类型，不要只根据单个状态码判断原因。

客户端建议

无论使用哪一种客户端，先确认：

• Base URL 是否正确。
• API Key 是否正确且未过期。
• 模型名称是否属于当前分组支持范围。
• 是否开启流式输出。
• 是否使用了不稳定的代理或 VPN。
• 是否一次性发送了超大上下文或大文件。
• 是否连续快速重试。

如果使用代理后频繁断流，可以切换到更稳定的节点，或暂时关闭不稳定代理后再试。

反馈时请提供

为了让 TkForA 维护人员快速定位问题，请尽量提供：

• 报错截图或完整的错误文本。
• request_id；如果存在，也请提供 cf-ray。
• 使用的模型。
• 大概发生时间，并注明时区。
• 使用的软件或客户端类型。
• 是否使用代理或 VPN。
• 可复现问题的最小请求描述，不要发送 API Key、Cookie 或完整认证链接。