错误码

错误码参考

当 API 请求失败时，响应会包含一个 HTTP 状态码和一个错误对象，详细说明出错原因。下表列出了所有可能的错误码：

错误响应格式

错误响应遵循以下结构：

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided.",
    "type": "error"
  }
}

错误处理最佳实践

实现重试逻辑

并非所有错误都应该重试，请参考以下指南：

• 可重试错误（429、500、503）： 这些是可能自行恢复的临时性错误。建议实现带指数退避的自动重试。
• 不可重试错误（400、401、403、404）： 这些错误表明请求或凭证存在问题。请先修复根本原因再重试。

指数退避策略

重试失败的请求时，使用指数退避策略以避免对服务器造成过大压力：

import time
import random

def make_request_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise e

            # 带随机抖动的指数退避
            delay = min(2 ** attempt + random.random(), 60)
            print(f"请求失败，{delay:.1f}秒后重试...（第 {attempt + 1}/{max_retries} 次尝试）")
            time.sleep(delay)

优雅处理速率限制

如果收到 429 rate_limit_exceeded 错误：

1. 遵守 Retry-After 头： 如果响应包含 Retry-After 头，请至少等待指定时间后再重试。
2. 降低并发量： 减少并行请求数量，确保在速率限制范围内。
3. 实现请求队列： 将请求排队，以可控的速率依次处理。

记录错误日志

始终记录错误响应的完整信息，包括完整的错误对象、请求 ID（如有）和时间戳。这些信息在联系支持团队排查持续性问题时非常重要。

发送前验证请求

通过在发送前验证请求数据，减少 400 invalid_request 错误：

• 确保所有必填字段都已填写。
• 确认模型名称与可用模型之一匹配（mimo-v2-pro、mimo-v2-omni、mimo-v2-tts、mimo-v2-flash）。
• 检查参数值在可接受范围内。
• 确认 API Key 已设置且不为空。