又来AI 文档
文档目录

Troubleshooting

排障与安全

遇到调用失败时，先看 HTTP 状态码和错误提示，再按下面表格检查令牌、Base URL、模型名、余额和客户端配置。

快速定位顺序

  1. 确认请求地址是否为 https://youlai.ai/v1/chat/completions 或客户端要求的兼容地址。
  2. 确认请求头里有 Authorization: Bearer sk-xxxxxxxx，Claude 兼容请求有 x-api-key: sk-xxxxxxxx。
  3. 确认 gpt-5.5 与控制台模型名完全一致。
  4. 确认账户余额充足，且令牌没有单独的额度、模型或 IP 限制。
  5. 如果 error.type、error.code 或 SDK 异常显示为上游错误，按“上游透传 / SDK 报错”表排查模型渠道。
  6. 用 curl 最小请求复现，排除客户端自身配置问题。

服务端错误码和处理办法

说明：平台中继接口通常返回 OpenAI 兼容结构 {"error":{"message","type","code"}}。本地错误会使用平台内部错误类型，上游模型错误会按上游返回透传；下面的“可能看到的提示”是 message、type 或 code 中的关键词，不承诺完全逐字一致。

状态码 可能看到的提示 可能原因 处理办法 验证方式
400 无效的请求
invalid JSON request body
field model must be a string		 JSON 不合法，model 字段类型错误，或把 Claude、Gemini、OpenAI 的请求格式混用。 复制“调用示例”里的最小 curl 请求重新测试；确认 Content-Type 是 application/json，且 model 是字符串。 用最小请求调用 /v1/chat/completions，确认能返回模型回复。
401 无效的令牌
invalid token
unauthorized		 令牌缺失、复制错误、已删除、已禁用、已过期、额度状态不可用，或请求头格式错误。 重新复制控制台中的令牌值；OpenAI 兼容请求使用 Authorization: Bearer sk-xxxxxxxx；Claude 兼容请求使用 x-api-key。 调用 /v1/models，如果仍为 401，重新创建令牌。
403 用户额度不足
token quota is not enough
该令牌无权访问模型
您的 IP 不在令牌允许访问的列表中		 账户余额不足，令牌单独额度不足，模型未授权，分组无权限，或命中了 IP 白名单限制。 先检查余额，再检查令牌额度和模型权限；如配置了 IP 白名单，确认当前服务器出口 IP 在白名单内。 充值或调整令牌权限后，重新发送同一条最小请求。
404 Invalid URL (GET /...)
not found		 接口路径写错，Base URL 重复拼接 /v1，或用错 HTTP 方法导致没有匹配到路由。 SDK 的 Base URL 填 https://youlai.ai/v1；直接 HTTP 请求用完整路径；聊天补全和 Messages 接口使用 POST。 用文档中的 curl 示例明确请求 /v1/chat/completions。
408 / 504 timeout
gateway timeout		 模型响应时间过长、网络不稳定、上游超时，或客户端超时时间太短。 降低 max_tokens，简化 prompt，开启流式输出，或调大客户端超时时间后重试。 用短 prompt 测试；若短请求正常，逐步恢复原上下文长度。
413 request body too large
read_request_body_failed
context length exceeded		 请求体过大，或上游模型返回上下文超限。 减少历史消息、压缩上下文、缩短文件内容；如果是上游上下文超限，换用上下文更大的模型。 删除历史上下文后发送同一问题，确认是否恢复。
429 您已达到请求数限制
too many requests
rate limit exceeded		 平台请求频率限制、并发过高、任务分组上游负载饱和，或上游模型限流。 降低并发，增加退避重试；自动化脚本使用指数退避，不要固定频率快速重试。 间隔 30 秒后单请求重试；脚本侧记录重试次数和间隔。
500 do_request_failed
bad_response_body
internal server error		 平台本地处理异常、请求上游失败、上游响应体无法解析，或某些本地参数校验被包装成内部错误。 先用最小请求排除客户端问题；如果持续出现，记录请求时间、模型名、状态码和 error.message 后联系管理员。 换一个模型或稍后重试，判断是否为单个渠道异常。
502 bad gateway
upstream error		 上游渠道不可用、网络转发异常，或模型服务临时失败。 稍后重试或切换模型；管理员需要检查渠道状态。 用同一令牌调用其他模型，判断是否为模型渠道问题。
503 model_not_found
分组 ... 下模型 ... 无可用渠道
service unavailable		 模型名不存在、当前分组没有可用渠道、渠道被禁用，或上游暂时不可用。 确认模型名以控制台为准；管理员需要检查模型定价、分组权限、渠道状态和上游可用性。 先访问 /v1/models，确认返回列表中包含 gpt-5.5。

上游透传 / SDK 报错

平台会把上游模型服务的错误转换或透传为 OpenAI 兼容错误；使用 OpenAI SDK 时，SDK 还会把 HTTP 错误包装成 AuthenticationError、RateLimitError 等异常名。看到这些报错时，要同时判断是用户自己的令牌、平台本地额度，还是管理员配置的上游渠道出问题。

报错名称 / 关键词 常见状态 常见来源 可能原因 处理办法
AuthenticationError
invalid_api_key
incorrect token		 401 OpenAI SDK、上游 OpenAI 兼容渠道、平台本地鉴权 用户令牌填错、请求头格式错误；如果用户令牌确认无误，也可能是管理员配置的上游渠道密钥已失效。 先用 /v1/models 验证用户令牌；仍失败就重新创建令牌。若本地令牌正常但聊天请求失败，管理员检查对应渠道的上游密钥。
RateLimitError
rate_limit_exceeded
too many requests		 429 OpenAI SDK、平台请求限流、上游模型限流 短时间请求过多、并发过高、模型渠道达到上游 RPM/TPM 限制，或当前分组上游负载饱和。 降低并发，增加指数退避；脚本不要立即无限重试。管理员可增加可用渠道、调整分组或更换模型。
InsufficientQuotaError
insufficient_quota
quota is not enough		 403 / 429 OpenAI SDK、平台本地额度、上游渠道额度 账户余额不足、令牌额度用完、套餐额度不足，或上游供应商账号余额不足。 用户先检查余额和令牌额度；若本地余额充足但仍返回上游 insufficient_quota，管理员检查渠道供应商余额。
BadRequestError
invalid_request_error
unsupported_parameter		 400 SDK 参数校验、上游模型服务 请求参数不被当前模型或接口支持，例如把 Responses API 参数发到 Chat Completions，或开启了模型不支持的工具调用。 对照“调用示例”使用对应接口；移除不确定的高级参数，只保留 model 和 messages 复测。
PermissionDeniedError
model_not_accessible
access denied		 403 上游模型服务、平台模型限制 当前令牌没有模型权限、上游账号未开通该模型、区域或项目权限不匹配，或平台令牌限制了模型。 确认控制台模型名可用；用户检查令牌模型权限，管理员检查渠道模型授权和分组绑定。
NotFoundError
model_not_found
invalid model		 404 / 503 SDK、平台分发器、上游模型服务 模型名写错、模型映射错误、所选分组没有可用渠道，或上游接口版本不支持该模型。 以控制台可用模型为准；管理员检查模型映射、渠道配置、分组权限和上游 API 版本。
APIConnectionError
APITimeoutError
connection error		 通常无 HTTP 状态 OpenAI SDK、本机网络、代理、上游连接 客户端到又来AI域名不可达，代理异常，TLS 失败，或平台到上游渠道连接超时。 先用 curl 测试 https://youlai.ai/v1/models；客户端网络正常但请求仍超时，降低输出长度或联系管理员检查上游渠道。
InternalServerError
BadGateway
ServiceUnavailable		 500 / 502 / 503 平台本地处理、网关、上游模型服务 上游临时故障、响应格式异常、渠道不可用，或平台内部处理异常。 稍后重试或切换模型；持续出现时记录请求时间、模型名、状态码和错误正文给管理员排查渠道。

客户端常见提示

下面这些是客户端、SDK、浏览器或本机网络层可能展示的提示，不是平台服务端固定返回的错误码。不同客户端版本和系统语言会让文案略有差异，处理时重点看 Base URL、令牌、模型名、网络和 Provider 类型。

客户端提示 常见客户端 / 场景 可能原因 处理办法 验证方式
fetch failed
ECONNREFUSED
network error		 Cherry Studio、Chatbox、Cline、Roo Code、Continue Base URL 写错、域名不可达、本地网络或代理阻断。 在浏览器或 curl 中访问 https://youlai.ai/v1/models；确认没有多余空格、中文标点和错误协议。 能打开 /v1/models 后，再回到客户端刷新模型。
SSL certificate problem
CERT_HAS_EXPIRED
ERR_CERT_COMMON_NAME_INVALID		 桌面客户端、命令行客户端、浏览器内置 WebView 域名证书异常、系统证书过旧，或客户端走了错误代理。 确认使用 https://youlai.ai/；检查本机代理和系统时间；不要在生产客户端关闭证书校验。 用浏览器直接打开 https://youlai.ai/，确认没有证书警告。
CORS error
blocked by CORS policy		 浏览器前端、NextChat 自托管前端、网页插件 浏览器预检请求、代理层或域名配置异常；即使跨域放行，前端直连也会暴露令牌。 不要在前端放令牌；优先通过后端服务、Serverless 函数或受控代理转发请求。 后端转发接口能返回模型回复后，再让前端调用自己的后端接口。
Cannot read properties of undefined
Unexpected response format		 Cherry Studio、Chatbox、Continue、部分自定义客户端 客户端不兼容返回格式，或把 Responses、Chat、Claude 格式混用。 换成客户端支持的 Provider 类型；OpenAI 兼容客户端优先使用 Chat Completions；Claude 类客户端使用 Claude 兼容地址。 切换 Provider 后，发送“你好”确认能收到标准回复。
model does not support tool calls
tools is not supported		 Cline、Roo Code、Cursor、带工具调用的 Agent 客户端 客户端开启了工具调用，但当前模型或渠道不支持该能力。 关闭工具调用、MCP、函数调用等高级能力，或选择明确支持工具调用的模型。 关闭工具调用后发送普通对话；普通对话成功说明问题在工具能力。
stream terminated
connection closed
socket hang up		 Codex CLI、Claude 类客户端、Cline、Roo Code 流式输出中断、网络断开、客户端超时或上游提前结束。 重试请求；如果频繁出现，关闭流式输出、降低输出长度，或调大客户端超时时间。 用非流式请求测试；非流式稳定时，再逐步开启流式输出。
model not found
No model selected		 Cherry Studio、Chatbox、Cursor、Continue、Dify 模型 ID 填错，客户端没有刷新可用模型，或该令牌没有模型权限。 手动填写 gpt-5.5，或刷新客户端可用模型；确认令牌有该模型权限。 调用 /v1/models，确认列表中包含要选择的模型。
Invalid URL
unsupported protocol		 所有支持自定义 Base URL 的客户端 Base URL 缺少 https://，末尾路径重复，或复制时带了不可见字符。 OpenAI 兼容 Base URL 填 https://youlai.ai/v1；Claude 类客户端按要求填写 https://youlai.ai/。 清空输入框后手动重填地址，再保存并重启客户端。

最小化复现请求

当客户端报错不清楚时，先用下面的 curl 测试平台是否可用。curl 能成功时，问题通常在客户端配置；curl 也失败时，再按错误码排查账号、令牌、模型或渠道。

curl "https://youlai.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

安全建议

  • 每个环境使用独立令牌，例如开发、测试、生产分别创建。
  • 生产服务使用环境变量或密钥管理系统读取令牌值，不要硬编码。
  • 不要把令牌放在浏览器前端代码中，也不要提交到公开仓库。
  • 离职、项目结束或怀疑泄露时，立即删除旧令牌并重新创建。
  • 给自动化工具使用的令牌设置合理额度，降低误用风险。