修复 OpenRouter 429 "Provider Returned Error"：速率限制、上游提供商与回退方案

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please slow down."
  }
}

{
  "error": {
    "code": 502,
    "message": "Provider returned error: [上游错误详情]"
  }
}

请求失败
├── HTTP 429 + OpenRouter 速率限制消息
│   → 原因：OpenRouter 层级的速率限制
│   → 修复：降低请求速率、升级套餐或增加延迟
│
├── HTTP 429 + 消息中包含 "provider returned error"
│   → 原因：上游提供商的速率限制透传
│   → 修复：检查提供商配额、切换模型或添加回退路由
│
├── HTTP 502/503 + "provider returned error"
│   → 原因：上游提供商宕机或暂时性故障
│   → 修复：带退避重试、切换提供商或使用回退
│
└── HTTP 400/401 + 错误消息
    → 原因：请求格式错误、密钥无效或模型未找到
    → 修复：检查 API 密钥、模型 ID 和请求格式

import asyncio
import random

async def call_with_backoff(make_request, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                # 如果有 retry-after 则遵守，否则使用带抖动的退避
                delay = min(30, (2 ** attempt) + random.random())
                await asyncio.sleep(delay)
            else:
                raise

async def smart_retry(make_request, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            error_msg = str(e)

            # 不重试：请求错误、认证错误、模型未找到
            if any(code in error_msg for code in ["400", "401", "404"]):
                raise

            # 带退避重试：速率限制或提供商错误
            if any(code in error_msg for code in ["429", "502", "503"]):
                delay = min(30, (2 ** attempt) + random.uniform(0, 1))
                await asyncio.sleep(delay)
            else:
                raise

curl https://api.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "evolink/auto",
    "messages": [
      {"role": "user", "content": "你的提示词"}
    ]
  }'

OpenRouter 请求失败
│
├── 来自 OpenRouter 的 429
│   ├── 免费套餐限制 → 升级账户
│   ├── 突发流量 → 添加并发控制
│   └── 持续高流量 → 检查套餐限制
│
├── "Provider returned error"
│   ├── 上游 429
│   │   ├── 提供商速率限制 → 降低速率或切换提供商
│   │   └── 共享配额耗尽 → 检查组织级限制
│   ├── 上游 502/503
│   │   ├── 提供商宕机 → 查看状态页面，等待或切换
│   │   └── 暂时性故障 → 带退避重试
│   └── 上游 400
│       ├── 上下文过长 → 截断或切换模型
│       ├── 参数无效 → 查看 API 文档
│       └── 模型已弃用 → 验证模型 ID
│
└── 其他错误
    ├── 401 → API 密钥无效
    ├── 404 → 模型未找到
    └── 网络错误 → 检查连接