UniterRouter API 错误码和故障排除指南。处理 GPT-4、Claude、Gemini API 的速率限制、认证错误、模型错误等问题的最佳实践。

错误处理

UniterRouter 使用标准 HTTP 响应码，并以与 OpenAI API 规范兼容的一致 JSON 格式返回错误。

错误响应格式

所有错误遵循以下结构：

{
  "error": {
    "message": "人类可读的错误信息",
    "type": "error_type",
    "param": "parameter_name",  // 可选：导致错误的参数
    "code": "error_code"
  }
}

HTTP 状态码

状态码	描述
`200`	成功
`400`	错误请求 —— 无效的请求参数
`401`	未授权 —— 无效或缺少 API 密钥
`402`	需要付款 —— 余额不足
`403`	禁止访问 —— 被 IAM 规则拒绝
`404`	未找到 —— 模型或资源不存在
`429`	请求过多 —— 超出速率限制
`500`	服务器内部错误 —— 服务端错误
`502`	网关错误 —— 上游提供商错误
`503`	服务不可用 —— 没有可用通道

错误类型

身份验证错误

invalid_api_key —— API 密钥无效或缺失。

{
  "error": {
    "message": "提供的 API 密钥不正确。你可以在 https://uniterouter.ai/dashboard 找到你的 API 密钥。",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

解决方案：验证你的 API 密钥是否正确，并在 Authorization 头中格式正确。

模型错误

model_not_found —— 请求的模型不存在或无法访问。

{
  "error": {
    "message": "模型 `gpt-5` 不存在或你没有访问权限。",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

解决方案：查看模型页面了解可用模型。

配额和计费错误

insufficient_quota —— 你的账户余额不足。

{
  "error": {
    "message": "你已超出当前配额，请检查你的计划和计费详情。",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

解决方案：在计费控制台为账户充值。

速率限制错误

rate_limit_exceeded —— 短时间内请求过多。

{
  "error": {
    "message": "达到速率限制。请控制你的请求频率。",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

解决方案：实现指数退避并降低请求频率。参见速率限制。

服务错误

no_available_channel —— 该模型没有可用的提供商通道。

{
  "error": {
    "message": "模型 `gpt-4o` 没有可用通道。请稍后重试或联系支持。",
    "type": "server_error",
    "code": "no_available_channel"
  }
}

解决方案：短暂延迟后重试。如果持续出现，请联系支持。

no_available_key —— 所有提供商 API 密钥都被限速或禁用。

{
  "error": {
    "message": "模型 `claude-3-opus` 没有可用的 API 密钥。所有密钥可能被限速或禁用。",
    "type": "server_error",
    "code": "no_available_key"
  }
}

解决方案：等待并重试，或考虑使用 BYOK（自带密钥）。

provider_error —— 上游提供商返回错误。

{
  "error": {
    "message": "上游提供商返回错误: context_length_exceeded",
    "type": "server_error",
    "code": "provider_error"
  }
}

解决方案：检查你的请求是否超出模型的上下文长度或其他限制。

service_unavailable —— 服务器过载。

{
  "error": {
    "message": "服务器当前过载。请稍后重试。",
    "type": "server_error",
    "code": "service_unavailable"
  }
}

解决方案：实现带指数退避的重试逻辑。

在代码中处理错误

Python

from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI(
    base_url="https://api.uniterouter.ai/v1",
    api_key="your_api_key",
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "你好！"}]
    )
except AuthenticationError as e:
    print(f"身份验证失败: {e}")
except RateLimitError as e:
    print(f"被限速，退避后重试: {e}")
except APIError as e:
    print(f"API 错误: {e.status_code} - {e.message}")

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uniterouter.ai/v1",
  apiKey: process.env.UNITEROUTER_API_KEY,
});

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "你好！" }],
  });
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    console.error("无效的 API 密钥");
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("被限速，需要实现退避");
  } else if (error instanceof OpenAI.APIError) {
    console.error(`API 错误: ${error.status} - ${error.message}`);
  }
}

重试策略

对于临时性错误（429、503、502），实现指数退避：

import time
import random

def call_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, ServiceUnavailableError) as e:
            if attempt == max_retries - 1:
                raise
            # 带抖动的指数退避
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

提示：OpenAI SDK 内置重试逻辑。使用 max_retries 参数进行配置。

错误码参考

错误码	HTTP 状态码	描述
`invalid_api_key`	401	API 密钥无效或缺失
`invalid_request`	400	请求体格式错误
`model_not_found`	404	模型不存在或无访问权限
`insufficient_quota`	402	账户余额不足
`rate_limit_exceeded`	429	请求过多
`no_available_channel`	503	没有可用提供商
`no_available_key`	503	所有提供商密钥已耗尽
`provider_error`	502	上游提供商错误
`service_unavailable`	503	服务器过载
`internal_error`	500	意外的服务器错误

下一步

查看速率限制以避免触及限制
了解 API 密钥管理
探索路由了解故障转移策略

错误处理

On this page