常见问题

本页整理使用 Potato 土豆 API 时最常见的排查方向。请求失败时，优先检查 API Key、账号额度、模型名称、令牌分组权限和接口地址。

快速判断

4xx 通常是客户端配置或请求内容问题，优先检查本地配置；5xx 通常是网关或上游服务问题，可以稍后重试，并保留 request-id 便于排查。

基础排查清单

检查项	说明
API Key	确认 Key 已完整复制，没有多余空格，并且未被禁用。
账号额度	在控制台确认余额或令牌额度仍然可用。
模型名称	从模型广场或控制台复制完整模型 ID，不要自行修改。
令牌分组	确认当前 API Key 所属分组有权限调用该模型。
Base URL	确认填写为 `https://www.potatoai.cc/v1`，不要漏掉 `/v1`。

HTTP 状态码可以帮助你快速定位问题归属：客户端、网关或上游服务。

状态码	含义	常见原因	建议操作
200	成功	正常响应；如果响应体为空，可能是端点不匹配。	检查端点是否与模型或接口类型匹配。
400	请求错误	JSON 无效、缺少字段、参数格式错误或模型名称拼写错误。	重新检查请求体和模型名称。
401	未授权	API Key 缺失、输入错误或已被禁用。	检查 `Authorization: Bearer sk-xxx` 格式。
403	禁止访问	API Key 无权访问该模型或当前分组未开放。	在控制台检查令牌分组权限。
404	未找到	URL 拼写错误，例如 `/v1/message` 少了 `s`。	调用 `/v1/models` 验证；检查 URL 拼写。
413	Request too large	Prompt 或输入内容超过模型上下文窗口。	缩短输入，或切换到更大上下文模型。
429	请求频率超限	QPS 超限，或账户额度已用完。	降低并发，并在控制台检查额度。
500	上游错误	上游模型服务异常。	等待 30 秒后重试；如仍失败，附上 `request-id` 提交工单。
502	网关错误	网关到上游的连接异常。	等待 1 分钟后重试。
503	服务不可用	上游过载或正在维护。	等待 1-5 分钟后重试。
504	网关超时	上游响应慢，或提示词过长。	缩短输入，或启用流式输出。
No response / stuck	无响应或请求卡住	本地网络、DNS、TLS 异常，或系统时间不准确。	检查网络，切换 DNS，并校正系统时间。

4xx 错误

4xx 通常是客户端问题，例如 Key、模型名、URL、请求体或权限配置不正确。大多数情况下，你可以通过检查本地配置自行修复。

5xx 错误

5xx 通常是网关或上游模型服务问题。建议等待一段时间后重试；如果持续失败，请附上 request-id、时间、模型名和简要请求场景提交工单。

如果模型价格、可用模型或额度消耗与预期不一致，请以控制台展示和最终账单记录为准。