AI API 常见报错排查大全：401、429、500、timeout 一篇搞定

AI API 常见报错排查大全：401、429、500、timeout 一篇搞定#

调用 AI API 遇到报错不要慌。本文汇总了通过 Crazyrouter 调用 GPT、Claude、Gemini、DeepSeek 等模型时最常见的错误码和解决方案，收藏备用。

快速索引#

错误码	含义	最常见原因
401	认证失败	API Key 错误或过期
403	权限不足	Key 没有该模型的访问权限
404	资源不存在	模型名称拼写错误
429	请求过多	触发速率限制
500	服务器错误	上游模型服务异常
502	网关错误	上游服务暂时不可用
503	服务不可用	模型过载或维护中
timeout	超时	请求内容过长或网络波动

1. 401 Unauthorized — 认证失败#

报错示例#

json

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

原因和解决#

原因 1：API Key 不正确

python

# ❌ 错误 — Key 有多余空格或换行
client = OpenAI(
    api_key="sk-你的Key ",  # 注意末尾空格
    base_url="https://crazyrouter.com/v1"
)

# ✅ 正确
client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1"
)

原因 2：Key 已被删除或禁用

到 Crazyrouter 控制台检查 Key 状态，必要时重新创建一个。

原因 3：环境变量没生效

python

import os

# 检查环境变量是否正确加载
api_key = os.getenv("OPENAI_API_KEY")
print(f"Key 前 8 位: {api_key[:8] if api_key else 'None'}")
# 应该输出: Key 前 8 位: sk-你的Ke

原因 4：用了 Anthropic SDK 但没改 base_url

Crazyrouter 统一使用 OpenAI SDK 格式，不要用 anthropic 库：

python

# ❌ 错误 — 不要用 anthropic SDK
from anthropic import Anthropic
client = Anthropic(api_key="sk-你的Key")

# ✅ 正确 — 用 openai SDK 调用 Claude
from openai import OpenAI
client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1"
)
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}]
)

2. 403 Forbidden — 权限不足#

报错示例#

json

{
  "error": {
    "message": "You don't have access to this model",
    "type": "permission_error"
  }
}

解决#

确认你的账户余额充足
部分高端模型可能需要一定的账户余额才能使用
到 Crazyrouter 定价页确认该模型是否可用

3. 404 Not Found — 模型不存在#

报错示例#

json

{
  "error": {
    "message": "The model 'gpt5.4' does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

常见拼写错误#

❌ 错误写法	✅ 正确写法
`gpt5.4`	`gpt-5.4`
`claude-4-sonnet`	`claude-sonnet-4-6`
`claude-opus4`	`claude-opus-4-7`
`deepseek-R1`	`deepseek-r1`
`gpt-4.1mini`	`gpt-4.1-mini`

解决#

模型名称区分大小写，注意连字符位置
到 Crazyrouter 定价页查看完整的模型名称列表
复制粘贴模型名称，避免手打出错

4. 429 Too Many Requests — 速率限制#

报错示例#

json

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 1s",
    "type": "rate_limit_error"
  }
}

解决方案#

方案 1：添加重试逻辑（推荐）

python

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1"
)

def call_with_retry(messages, model="claude-sonnet-4-6", max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages
            )
            return response
        except RateLimitError as e:
            wait_time = 2 ** attempt  # 指数退避: 1s, 2s, 4s
            print(f"速率限制，{wait_time}秒后重试...")
            time.sleep(wait_time)
    raise Exception("重试次数用尽")

# 使用
response = call_with_retry([{"role": "user", "content": "你好"}])

方案 2：控制并发数

python

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1"
)

# 用信号量限制并发
semaphore = asyncio.Semaphore(5)  # 最多 5 个并发请求

async def call_api(message):
    async with semaphore:
        response = await client.chat.completions.create(
            model="claude-sonnet-4-6",
            messages=[{"role": "user", "content": message}]
        )
        return response.choices[0].message.content

# 批量调用
async def main():
    tasks = [call_api(f"问题 {i}") for i in range(20)]
    results = await asyncio.gather(*tasks)
    return results

asyncio.run(main())

方案 3：联系客服提升限额

如果业务需要更高的并发，联系 Crazyrouter 客服申请提升速率限制。

5. 500 Internal Server Error — 服务器错误#

报错示例#

json

{
  "error": {
    "message": "Internal server error",
    "type": "server_error"
  }
}

解决#

这通常是上游模型服务（OpenAI / Anthropic / Google）的临时问题：

等几秒重试 — 大多数 500 错误是暂时的
换个模型试试 — 如果 GPT-5.4 报 500，试试 Claude Sonnet
检查请求内容 — 过长的输入或特殊字符可能触发上游错误

python

# 带自动重试的健壮调用
def robust_call(messages, model="claude-sonnet-4-6", fallback_model="gpt-5.4"):
    try:
        return client.chat.completions.create(model=model, messages=messages)
    except Exception as e:
        if "500" in str(e) or "502" in str(e) or "503" in str(e):
            print(f"{model} 暂时不可用，切换到 {fallback_model}")
            return client.chat.completions.create(model=fallback_model, messages=messages)
        raise

6. 502 / 503 — 网关错误 / 服务不可用#

原因#

上游模型服务正在维护或过载
某个特定模型暂时不可用

解决#

等 1-2 分钟后重试
切换到其他模型（Crazyrouter 支持 300+ 模型，总有能用的）
查看 Crazyrouter 状态页确认是否有已知故障

7. Timeout — 请求超时#

报错示例#

code

openai.APITimeoutError: Request timed out

原因和解决#

原因 1：默认超时时间太短

python

# ✅ 设置更长的超时时间
client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1",
    timeout=120.0  # 120 秒
)

原因 2：请求内容太长，生成时间久

python

# ✅ 使用流式输出避免超时
stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "很长的内容..."}],
    stream=True  # 流式输出不会超时
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

原因 3：max_tokens 设置过大

python

# ❌ 不要设太大
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "写个 hello world"}],
    max_tokens=100000  # 太大了，简单任务不需要
)

# ✅ 根据任务合理设置
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "写个 hello world"}],
    max_tokens=500  # 够用就行
)

8. 中文乱码#

原因#

终端或文件编码不是 UTF-8。

解决#

python

# Python 文件开头
# -*- coding: utf-8 -*-

# 终端编码设置
import sys
sys.stdout.reconfigure(encoding='utf-8')

# 写入文件时指定编码
with open("output.txt", "w", encoding="utf-8") as f:
    f.write(response.choices[0].message.content)

Node.js 通常不会有这个问题，默认就是 UTF-8。

9. base_url 配置错误#

常见错误#

python

# ❌ 少了 /v1
client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://api.crazyrouter.com"  # 缺少 /v1
)

# ❌ 多了斜杠
client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1/"  # 末尾多了 /
)

# ❌ 用了 http 而不是 https
client = OpenAI(
    api_key="sk-你的Key",
    base_url="http://api.crazyrouter.com/v1"  # 应该是 https
)

# ✅ 正确写法
client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1"
)

10. 通用排查清单#

遇到任何报错，按这个顺序检查：

✅ API Key 是否正确（sk- 开头，无多余空格）
✅ Base URL 是否是 https://crazyrouter.com/v1
✅ 模型名称是否拼写正确
✅ 账户余额是否充足
✅ 网络是否正常（ping crazyrouter.com）
✅ SDK 版本是否最新（pip install --upgrade openai）
✅ 请求参数是否合法（temperature 0-2，max_tokens 合理范围）

python

# 一键诊断脚本
from openai import OpenAI

def diagnose():
    try:
        client = OpenAI(
            api_key="sk-你的Key",
            base_url="https://crazyrouter.com/v1",
            timeout=30.0
        )
        
        response = client.chat.completions.create(
            model="gpt-4.1-mini",  # 用便宜的模型测试
            messages=[{"role": "user", "content": "说'连接成功'"}],
            max_tokens=10
        )
        
        print(f"✅ 连接成功！响应: {response.choices[0].message.content}")
        print(f"✅ 模型: {response.model}")
        
    except Exception as e:
        print(f"❌ 连接失败: {type(e).__name__}: {e}")

diagnose()

💡 实测验证（2026 年 5 月）：我们用类似的诊断脚本通过 Crazyrouter 测试了 gpt-5.4、claude-sonnet-4-6、deepseek-r1、deepseek-v4-pro 四个模型，全部连接成功并返回正常响应。如果你的诊断脚本报错，大概率是 Key 或网络问题，按上面的清单逐项排查即可。

生产环境最佳实践#

完整的错误处理模板#

python

from openai import OpenAI, APIError, RateLimitError, APITimeoutError, AuthenticationError
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = OpenAI(
    api_key="sk-你的Key",
    base_url="https://crazyrouter.com/v1",
    timeout=120.0,
    max_retries=0  # 我们自己处理重试
)

def call_ai(
    messages,
    model="claude-sonnet-4-6",
    fallback_model="gpt-4.1-mini",
    max_retries=3,
    **kwargs
):
    """带完整错误处理的 AI API 调用"""
    
    for attempt in range(max_retries):
        current_model = model if attempt < max_retries - 1 else fallback_model
        
        try:
            response = client.chat.completions.create(
                model=current_model,
                messages=messages,
                **kwargs
            )
            return response.choices[0].message.content
            
        except AuthenticationError:
            logger.error("API Key 无效，请检查配置")
            raise  # 认证错误不重试
            
        except RateLimitError:
            wait = 2 ** attempt
            logger.warning(f"速率限制，{wait}秒后重试 (第{attempt+1}次)")
            time.sleep(wait)
            
        except APITimeoutError:
            logger.warning(f"请求超时，重试 (第{attempt+1}次)")
            time.sleep(1)
            
        except APIError as e:
            if e.status_code in (500, 502, 503):
                logger.warning(f"服务器错误 {e.status_code}，切换模型重试")
                time.sleep(2)
            else:
                logger.error(f"API 错误: {e}")
                raise
    
    raise Exception(f"调用失败，已重试 {max_retries} 次")

# 使用
result = call_ai(
    messages=[{"role": "user", "content": "你好"}],
    model="claude-sonnet-4-6",
    temperature=0.7,
    max_tokens=2000
)
print(result)

总结#

90% 的 API 报错都是这几个原因：

Key 错了或余额不足 → 检查 Key 和余额
模型名拼错了 → 去定价页复制正确名称
base_url 格式不对 → 用 https://crazyrouter.com/v1
速率限制 → 加重试逻辑
超时 → 用流式输出或加大 timeout

遇到搞不定的问题，联系 Crazyrouter 客服，提供错误信息和请求参数，通常能快速定位。

AI API 常见报错排查大全：401、429、500、timeout 一篇搞定