故障排除

    认证类错误

    错误信息HTTP 状态码原因解决方案
    invalid api key401API Key 无效、已过期、已撤销或已禁用请进入控制台 → API Keys 页面，确认 Key 状态为"活跃"，如已过期请重新生成

    路由与模型错误

    错误信息HTTP 状态码原因解决方案
    no model config found for: {model}404请求的模型 ID 不存在进入模型列表，确认模型 ID 拼写正确
    model field is required400请求体中缺少 model 字段在请求 JSON 中添加 "model": "模型名称"
    invalid or empty requested model400请求的模型名称为空或非法进入模型列表，确认使用正确的模型 ID 格式
    unknown api path404API 路径错误请确认 Base URL 为 https://api.gate.ai/openai/v1 或 https://api.gate.ai/anthropic

    请求参数错误

    错误信息HTTP 状态码原因解决方案
    invalid JSON body400请求体 JSON 格式不合法检查请求体是否为合法的 JSON 格式
    failed to read request body400请求体读取失败确认请求体未损坏，Content-Type 设置为 application/json
    failed to rewrite request body500请求体重写失败（网关内部）请重试，若持续出现，请联系技术支持
    images are not supported by this model400目标模型不支持图片输入更换支持多模态（图片）的模型，如 gpt-4o
    audio is not supported by this model400目标模型不支持音频输入更换支持音频输入的模型
    unsupported parameter: max_tokens400部分模型不支持 max_tokens 参数改用 max_completion_tokens 参数

    配额与限流错误

    错误信息HTTP 状态码原因解决方案
    api key budget quota exceeded429API Key 预算额度已用尽进入控制台 → API Keys → 预算设置，提高预算上限或等待配额重置
    guardrail budget limit exceeded429护栏预算限制已超出检查护栏配置中的预算限制，调高限额或降低使用频率
    organization guardrail budget limit exceeded429组织级护栏预算已超出联系组织管理员调整组织级预算限制
    model not allowed by guardrail policy403模型不在护栏策略允许范围内进入控制台 → 护栏设置，将目标模型添加到允许列表
    The free model usage has reached its daily global limit today.429免费模型全局日限额已达上限等待次日重置，或升级到付费计划使用无限制模型
    The free model usage has reached its daily limit today.429个人免费模型日限额已达上限等待次日重置，或升级到付费计划
    Guest daily spending limit exceeded. Please try again tomorrow or upgrade to a paid plan.429游客身份日累计限额已超出注册账号并升级到付费计划，或等待次日重置

    计费与余额错误

    错误信息HTTP 状态码原因解决方案
    Pending payment {amount} USD — Please top up...402账户余额不足且存在欠费前往 Gate Pay 完成充值
    Insufficient balance and account in debt402余额不足且账户处于欠费状态前往 Gate Pay 完成充值
    billing model info not found for model "{model}"400模型的计费信息不存在确认模型 ID 正确，若为新模型，请联系技术支持配置计费规则
    billing model info is ambiguous for model "{model}"400模型计费信息存在歧义（多条匹配）请联系技术支持排查模型计费配置
    billing configuration error500计费规则配置错误（服务端）请联系技术支持修复计费配置

    上游服务错误

    错误信息HTTP 状态码原因解决方案
    bad gateway502网关与上游服务通信失败请重试，若持续出现，请检查服务状态页或联系技术支持
    upstream service unavailable502上游 AI Provider 不可用稍后重试，或切换到其他可用模型
    upstream service error502上游 AI Provider 返回错误检查请求参数是否符合目标模型要求；若持续出现请联系技术支持
    request timeout504请求上游超时减少输入长度或增加超时时间后重试
    no provider handler configured for protocol502网关未配置对应的协议处理器请联系技术支持检查网关配置

    服务端内部错误

    错误信息HTTP 状态码原因解决方案
    internal server error500网关内部错误请重试，若持续出现，请携带 Request ID 联系技术支持
    failed to record request log500请求日志记录失败不影响请求结果，可忽略；若频繁出现请联系技术支持
    failed to list models500模型列表查询失败请重试，若持续出现，请联系技术支持

    常见场景速查

    Base URL 错误

    bash
    1# ❌ 错误2https://api.gate.ai/v1/chat/completions34# ✅ 正确5https://api.gate.ai/openai/v1/chat/completions  # openai 协议6https://api.gate.ai/anthropic/v1/messages  # anthropic 协议

    max_tokens 参数不兼容

    javascript
    1// ❌ 部分模型不支持2{ "model": "gpt-4o", "max_tokens": 100 }34// ✅ 使用 max_completion_tokens5{ "model": "openai/gpt-5.5", "max_completion_tokens": 100 }

    API Key 格式

    bash
    1# ✅ 正确的请求头2Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx # openai 协议3X-api-key: sk-xxxxxxxxxxxxxxxxxxxx # anthropic 协议