错误码#

UniGateway API 所有错误响应的完整参考，包含原因和处理方式。

错误响应格式#

所有错误遵循统一的 JSON 结构：

{
  "error": {
    "code": "429",
    "type": "rate_limit",
    "message": "Rate limit exceeded"
  }
}

错误速查表#

鉴权错误#

401 — auth_invalid#

原因： API Key 缺失、无效或已过期。

处理方式：

1. 确认 Authorization: Bearer <key> 请求头格式正确
2. 登录控制台确认密钥未被吊销
3. 确保密钥值中没有多余空格或换行
4. 使用环境变量时确认已正确设置和导出

权限错误#

403 — access_denied#

原因： API Key 无权访问请求的资源。

处理方式：

1. 检查是否用标准密钥访问了管理接口（需管理密钥）
2. 确认账户有权访问请求的模型或功能

403 — safety_check_failed#

原因： 输入内容被上游安全策略拦截。

处理方式：

1. 调整提示词、图片或工具输入内容
2. 移除可能触发安全规则的描述
3. 切换到安全阈值不同的模型

计费错误#

402 — insufficient_credit#

原因： 账户余额为负（欠费）。

处理方式： 前往 设置 → 计费 充值

402 — reject_no_credit#

原因： 账户余额为零或过低，该模型需要正余额才能调用。

处理方式：

1. 充值账户余额
2. 切换到允许低余额访问的模型或方案

参数校验错误#

400 — invalid_params#

请求参数未通过校验时的具体子情况：

413 — prompt_too_long#

原因： 请求体（含所有消息）超过模型最大上下文长度。

处理方式：

1. 减少消息数量或长度
2. 使用支持更大上下文窗口的模型
3. 摘要历史对话而非包含完整内容

422 — provider_unprocessable#

原因： 请求通过了平台校验，但上游 Provider 无法处理。通常因为上游对字段结构、工具或多模态输入有更严格的要求。

处理方式：

1. 查看响应 message 字段中的具体描述
2. 确认所有参数与所选模型兼容
3. 移除可选/高级参数，用最小请求重试

模型可用性错误#

404 — model_not_available#

原因： 模型存在但当前账户无法访问。

处理方式：

1. 升级套餐以包含目标模型

404 — invalid_model#

原因： 指定的模型标识符不匹配任何已知模型。

处理方式：

1. 检查模型名称拼写
2. 查询 GET /v1/models 获取有效标识符

404 — model_not_supported#

原因： 模型存在但不支持当前调用的 API 接口。

处理方式：

1. 检查模型详情页确认支持的 API
2. 切换到支持当前 API 的模型

限流错误#

429 — rate_limit#

原因： 请求频率超过允许的限制，可能来自平台级或上游 Provider 限流。

处理方式：

1. 降低请求频率
2. 在请求间添加延迟或使用指数退避
3. 更均匀地分散高峰流量

服务端和上游错误#

500 — internal_server_error#

原因： 平台侧发生意外错误。

处理方式：

1. 指数退避重试 — 多数 500 错误为临时性
2. 若持续出现，联系客服并提供响应头中的 X-UniGateway-RequestId

500 — provider_error / provider_api_error#

原因： 请求到达上游 Provider，问题来自 Provider 侧。

处理方式：

1. 指数退避重试
2. 若持续出现，联系客服并提供 X-UniGateway-RequestId

502 — no_provider_available#

原因： 当前无可用上游 Provider 处理请求。可能原因：

• 指定的 Provider 不存在
• 该模型所有配置的上游 Provider 均故障
• 所有 Provider 重试后均失败

处理方式：

1. 放宽或移除 Provider 特定路由规则
2. 短暂等待后重试
3. 重试请求

503 — service_unavailable#

原因： 平台暂时不可用，通常在维护或容量事件期间。

处理方式：

1. 短暂延迟后重试
2. 查看状态页了解进行中的事件

524 — provider_timeout#

原因： 上游 Provider 在超时窗口内未响应。

处理方式：

1. 指数退避重试
2. 考虑使用更快的模型变体
3. 如果模型接近处理上限，减少提示词长度

流式请求的错误处理#

使用 stream: true 时，错误的表现形式与非流式请求不同。

流中发生的错误#

流式传输开始后发生的错误不会回退为标准 JSON 错误体。流会终止或在流中发出失败事件。客户端应处理：

• 流消费前的 HTTP 状态码评估
• 事件流完整性检查（查找 data: [DONE]）
• 流内错误事件解析
• 连接中断处理

SSE Keep-Alive#

长时间运行的请求中可能收到 SSE 注释：

: UNIGATEWAY PROCESSING

这不是错误 — 是为防止连接超时定期发送的保活信号。根据 SSE 规范，客户端解析器应忽略以 : 开头的行。

流断开#

如果客户端主动断开（如取消请求），服务端会清理进行中的流。客户端主动断开不会产生错误响应。

错误处理最佳实践#

1. 始终基于 type 字段处理错误 — 用 type 做程序逻辑分支；message 仅用于展示，内容可能变更

2. 对可重试错误实现重试逻辑：

   类别	状态码
   可重试	429, 500, 502, 503, 524
   不可重试	400, 401, 402, 403, 404, 413, 422

3. 保存 X-UniGateway-RequestId — 联系客服时提供此 ID 可加速定位

4. 优雅处理流式响应 — 始终处理不完整响应和连接中断

5. 使用指数退避重试 — 逐步增加间隔（如 1s → 2s → 4s → 8s），加入随机抖动避免"惊群效应"

示例重试逻辑（Python）#

import time
import random
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_UNIGATEWAY_API_KEY>",
    base_url="https://api.unigateway.ai/v1",
)

max_retries = 3
for attempt in range(max_retries):
    try:
        resp = client.chat.completions.create(
            model="gpt-5.4",
            messages=[{"role": "user", "content": "你好"}],
        )
        print(resp.choices[0].message.content)
        break
    except Exception as e:
        if attempt < max_retries - 1:
            delay = min(0.3 * (2 ** attempt), 8) + random.uniform(0, 0.1)
            time.sleep(delay)
        else:
            raise

常见问题#

问：同一请求某些模型正常但某些返回 404？ 答：不同方案包含不同模型列表。升级套餐可获得完整模型访问。

问：偶尔出现 500 错误，需要担心吗？ 答：分布式系统中偶发 500 是正常的。实现指数退避自动重试即可。如果错误率持续偏高，联系客服。

问：流式请求中 UNIGATEWAY PROCESSING 是什么？ 答：这是 SSE 保活注释（以 : 开头），表示请求仍在处理中。不是错误，SSE 客户端应按规范忽略注释行。

问：如何知道哪个上游 Provider 处理了我的请求？ 答：将响应头中的 X-UniGateway-RequestId 提供给客服团队即可追踪请求路径。