铸云 AI

错误处理指南

了解 Mint Cloud AI API 的错误响应格式、状态码和最佳实践,帮助你构建健壮的应用程序。

错误响应格式

所有 API 错误都遵循统一的 JSON 格式,便于程序化处理:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "请求频率超过限制,请稍后重试",
    "type": "rate_limit_error"
  }
}

code

错误码,标识错误的类型

message

人类可读的错误描述

type

错误类型分类

HTTP 状态码

API 使用标准 HTTP 状态码来表示请求结果:

状态码说明常见原因
200成功正常响应
400请求错误参数格式错误、缺少必填字段
401认证失败API Key 无效或过期
403权限不足账户无权访问该模型
404资源不存在模型 ID 错误
429触发限流超过速率限制
500服务器错误内部错误,请重试
502上游错误模型供应商服务异常
503服务不可用服务维护中

错误码类型

API 返回的错误码用于标识具体错误类型:

authentication_error

认证失败,API Key 无效或已过期

invalid_request

请求参数格式错误或缺少必填字段

rate_limit_exceeded

请求频率超过限制,请等待后重试

server_error

服务器内部错误,通常是临时性的

invalid_api_key

API Key 不存在或已被禁用

model_not_found

请求的模型不存在或无权访问

错误处理示例

以下示例展示如何在 Python 中处理各种 API 错误:

Python 错误处理
import time
from openai import RateLimitError, AuthenticationError, APIError

def call_api_with_retry(client, model, messages, max_retries=3):
    """带重试的 API 调用"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages
            )
            return response
        
        except RateLimitError:
            # 处理限流,等待后重试
            wait_time = 2 ** attempt  # 指数退避
            print(f"触发限流,等待 {wait_time} 秒后重试...")
            time.sleep(wait_time)
        
        except AuthenticationError:
            # API Key 无效
            print("认证失败:请检查 API Key 是否正确")
            raise
        
        except APIError as e:
            # 其他 API 错误
            print(f"API 错误:{e}")
            if attempt == max_retries - 1:
                raise
            time.sleep(1)

# 使用示例
try:
    result = call_api_with_retry(
        client=client,
        model="openai/gpt-4o",
        messages=[{"role": "user", "content": "你好"}]
    )
    print(result.choices[0].message.content)
except Exception as e:
    print(f"请求最终失败:{e}")

重试策略

指数退避

每次重试之间等待的时间成倍增加,例如:1秒、2秒、4秒、8秒。 这可以避免在服务器负载高时进一步压垮服务。

有限重试次数

设置最大重试次数(通常 3-5 次),避免无限重试。 超过最大次数后,记录错误并向用户报告。

区分错误类型

限流错误(429)适合重试,认证错误(401)不应重试, 服务器错误(500、502、503)可以重试。

添加抖动

在退避时间上添加随机抖动(0.5-1秒),避免多客户端同时重试造成雷鸣羊群效应。

最佳实践

1

始终检查响应状态

不要假设请求一定成功,在处理响应前检查状态码和错误字段。

2

提供有意义的错误信息

将技术错误转化为用户友好的提示,帮助用户理解问题并采取行动。

3

记录完整错误上下文

记录错误码、错误信息、请求参数和时间戳,便于排查问题和监控系统。

4

实现优雅降级

当 API 不可用时,提供备选方案或缓存数据,确保核心功能可用。

5

使用超时设置

为所有 API 请求设置合理的超时时间,避免无限等待导致的程序卡死。