跳转到主要内容

​
概述

本文档提供了使用 Wisdom Gate API 时可能遇到的所有错误码的全面指南。了解这些错误码将帮助您在应用程序中实现正确的错误处理和故障排除。
错误响应格式所有错误响应遵循一致的格式：
{
  "error": {
    "message": "错误描述",
    "type": "error_type",
    "param": "parameter_name",
    "code": "error_code"
  }
}

​
HTTP 状态码

​
400 Bad Request（错误请求）

代码说明：请检查您的请求格式，通常是客户端错误。 常见原因：
  • 请求体中的 JSON 格式无效
  • 缺少必需参数
  • 参数值或类型无效
  • 请求结构格式错误
如何修复：
  1. 验证您的请求体是否为有效的 JSON
  2. 检查是否包含所有必需参数
  3. 验证参数类型是否符合 API 规范
  4. 查看 OpenAPI 规范 了解正确的请求格式
示例： 
{
  "error": {
    "message": "Invalid request format",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "invalid_format"
  }
}

​
401 Invalid Token（无效令牌）

代码说明：API 密钥验证失败。尝试更换模型测试您的 API 密钥是否正确；如果更换模型后正常，请联系管理员反馈处理。 常见原因：
  • API 密钥缺失或无效
  • API 密钥已过期或被撤销
  • Authorization 头格式不正确
如何修复：
  1. 验证您的 API 密钥是否正确且有效
  2. 检查 Authorization 头格式：Bearer YOUR_API_KEY
  3. 尝试使用不同的模型测试 API 密钥是否有效
  4. 如果更换模型后正常，请联系管理员获取帮助
  5. 如有必要，重新生成您的 API 密钥
示例： 
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

​
403 Token Group XXX Has Been Disabled（令牌组已被禁用）

代码说明：通常是令牌权限问题。如果创建并使用新令牌后仍然报错，需要联系管理员检查。例如，O1 系列模型不支持 system 参数。 常见原因：
  • 令牌组已被禁用
  • 请求操作权限不足
  • 模型特定参数限制（例如，O1 系列不支持 system 参数）
如何修复：
  1. 创建并使用新令牌
  2. 检查您的令牌是否有所需权限
  3. 验证模型特定的参数限制
  4. 如果问题持续，请联系管理员
示例： 
{
  "error": {
    "message": "Token Group XXX Has Been Disabled",
    "type": "permission_error",
    "code": "token_group_disabled"
  }
}

​
404 Not Found（未找到）

代码说明：请检查 Base URL 是否填写正确，尝试添加 /v1 或最后的斜杠 /。 常见原因：
  • 端点 URL 不正确
  • 路径中缺少 /v1 前缀
  • 缺少尾部斜杠
  • 资源 ID 无效（例如，video_id、模型名称）
如何修复：
  1. 验证端点 URL 是否正确
  2. 确保路径包含 /v1 前缀（例如，/v1/chat/completions）
  3. 检查是否需要尾部斜杠
  4. 验证资源 ID 是否存在且正确
  5. 查看 API 参考文档 了解正确的端点
示例： 
{
  "error": {
    "message": "Resource not found",
    "type": "invalid_request_error",
    "code": "not_found"
  }
}

​
413 Request Entity Too Large（请求实体过大）

代码说明：提示词可能过长。请缩短您的提示词并重试，确认更短的提示词是否可以正常调用。 常见原因：
  • 请求体超出大小限制
  • 提示文本过长
  • 对话历史中消息过多
  • 文件附件过大
如何修复：
  1. 缩短您的提示文本
  2. 减少对话历史中的消息数量
  3. 移除不必要的上下文或消息
  4. 将大请求拆分成较小的块
  5. 如果使用文件附件，压缩或减小文件大小
示例： 
{
  "error": {
    "message": "Request entity too large",
    "type": "invalid_request_error",
    "code": "request_too_large"
  }
}

​
429 Current Group Upstream Load Is Saturated（当前组上游负载饱和）

代码说明：OpenAI 对单个账户有速率限制，429 表示后端账户的并发使用量过高并触发了速率限制。请继续尝试调用。 常见原因：
  • 并发请求过多
  • 账户速率限制超限
  • 后端账户饱和
如何修复：
  1. 实现指数退避重试逻辑
  2. 降低请求频率
  3. 在请求之间添加延迟
  4. 对批量操作使用请求队列
  5. 使用适当的退避策略继续重试
重试实现示例： 
import requests
import time
import random

def make_request_with_retry(url, headers, data, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data)
            
            if response.status_code == 429:
                # 带抖动的指数退避
                wait_time = (2 ** attempt) + random.random()
                print(f"速率受限。等待 {wait_time:.2f} 秒...")
                time.sleep(wait_time)
                continue
            
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                wait_time = (2 ** attempt) + random.random()
                time.sleep(wait_time)
            else:
                raise
错误响应示例： 
{
  "error": {
    "message": "Current Group Upstream Load Is Saturated",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

​
500 Internal Server Error（服务器内部错误）

代码说明：服务器内部错误。可能是代理服务器或 OpenAI 服务器的问题，与用户无关。请重试，如果多次出错请联系管理员。 常见原因：
  • 代理服务器问题
  • 上游服务（OpenAI）服务器问题
  • 临时服务中断
如何修复：
  1. 短暂延迟后重试请求
  2. 检查服务状态（如可用）
  3. 如果错误持续，请联系管理员
  4. 实现带指数退避的重试逻辑
示例： 
{
  "error": {
    "message": "Internal server error",
    "type": "server_error",
    "code": "internal_error"
  }
}

​
503 No Available Channel for Model XXXX Under Current Group NNN（当前组下无可用模型通道）

代码说明：代理平台后端的管理问题。请联系管理员添加此模型后再尝试调用。如果多次出错，请联系管理员。 常见原因：
  • 模型在您的令牌组中不可用
  • 后端模型配置问题
  • 模型暂时不可用
如何修复：
  1. 验证模型名称是否正确
  2. 检查模型是否在您的套餐中可用
  3. 联系管理员将模型添加到您的组
  4. 如有可用，尝试使用替代模型
示例： 
{
  "error": {
    "message": "No Available Channel for Model gpt-4 Under Current Group 123",
    "type": "service_unavailable",
    "code": "model_unavailable"
  }
}

​
504 Gateway Timeout（网关超时）

代码说明：网关超时，未能在指定时间内从上游服务器获取响应。请重试，多次出错请联系管理员。 常见原因：
  • 上游服务器（OpenAI）响应时间过长
  • 网络连接问题
  • 请求超时
如何修复：
  1. 重试请求
  2. 检查网络连接
  3. 降低请求复杂度或大小
  4. 如可能，增加超时设置
  5. 如果错误持续，请联系管理员
示例： 
{
  "error": {
    "message": "Gateway timeout",
    "type": "timeout_error",
    "code": "gateway_timeout"
  }
}

​
524 Connection Timeout（连接超时）

代码说明：服务器未在指定时间内完成请求，可能是 Wisdom Gate 通道拥堵导致。请重试，多次出错请联系管理员。 常见原因：
  • 服务器拥堵
  • 网络延迟问题
  • 请求处理超时
如何修复：
  1. 延迟后重试请求
  2. 检查服务是否拥堵
  3. 降低请求大小或复杂度
  4. 如果多次出错，请联系管理员
示例： 
{
  "error": {
    "message": "Connection timeout",
    "type": "timeout_error",
    "code": "connection_timeout"
  }
}

​
错误处理最佳实践

​
1. 实现全面的错误处理

始终在您的应用程序中优雅地处理错误： 
import requests

def handle_api_request(url, headers, data):
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 429:
            # 处理速率限制
            return handle_rate_limit(e.response)
        elif e.response.status_code == 401:
            # 处理认证错误
            return handle_auth_error(e.response)
        elif e.response.status_code >= 500:
            # 处理服务器错误
            return handle_server_error(e.response)
        else:
            # 处理其他客户端错误
            return handle_client_error(e.response)
    except requests.exceptions.RequestException as e:
        # 处理网络错误
        return handle_network_error(e)

​
2. 使用指数退避进行重试

对于瞬态错误（429、500、503、504、524），实现指数退避： 
import time
import random

def retry_with_backoff(func, max_retries=5, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt < max_retries - 1:
                delay = (base_delay * (2 ** attempt)) + random.random()
                time.sleep(delay)
            else:
                raise

​
3. 记录错误以便调试

始终记录错误详情以便故障排除： 
import logging

logging.error(f"API 错误: {error_code} - {error_message}")
logging.error(f"请求: {request_data}")
logging.error(f"响应: {response_data}")

​
4. 提供用户友好的错误消息

将技术性错误码转换为用户友好的消息： 
ERROR_MESSAGES = {
    400: "请检查您的请求格式",
    401: "API 密钥无效。请验证您的凭证",
    403: "权限被拒绝。请检查您的令牌权限",
    404: "资源未找到。请验证端点 URL",
    413: "请求过大。请减少提示词大小",
    429: "超出速率限制。请稍后重试",
    500: "服务器错误。请重试",
    503: "服务不可用。请联系客服",
    504: "请求超时。请重试",
    524: "连接超时。请重试"
}

​
错误码摘要表

状态码错误类型建议重试需要用户操作
400错误请求否修复请求格式
401无效令牌否验证 API 密钥
403权限被拒绝否检查权限或联系管理员
404未找到否验证端点 URL
413请求过大否减小请求大小
429速率限制是使用退避策略重试
500服务器错误是重试或联系管理员
503服务不可用是联系管理员
504网关超时是重试
524连接超时是重试

​
获取帮助

如果按照故障排除步骤操作后仍然遇到错误：
  1. 查看 模型目录 了解模型可用性和要求
  2. 查看 API 参考 了解正确的端点使用
  3. 联系客服，提供：
    • 错误码和消息
    • 请求详情（不含敏感数据）
    • 重现步骤
    • 您的 API 密钥组信息（如适用）