去年双十一，我负责的电商平台 AI 客服系统经历了前所未有的流量洪峰。凌晨零点刚过 3 秒，请求量从日常的 200 QPS 瞬间飙升至 15,000 QPS，系统开始疯狂报错。那一夜，我处理了 47 种不同的 API 错误，最终总结出一套完整的 AI API 错误对照表和应对方案。今天这篇文章，我将毫无保留地分享这些实战经验，帮助你避免重蹈我的覆辙。
为什么你需要一个统一的错误码对照表
当你的系统同时接入多个 AI 服务商时，每个平台的错误码体系各不相同：OpenAI 用 error.code，Claude 用 type 字段，Gemini 用 error.status，DeepSeek 又是一套独立的规范。没有统一的错误处理逻辑，你的系统会在生产环境中频繁出现"未知错误"和"死循环重试"。
我曾经踩过一个坑：系统接入了 4 个 AI 服务商，某天 DeepSeek 返回了 429 错误，但我的重试逻辑只针对 OpenAI 的 rate_limit_exceeded，导致请求被错误地判定为"服务器错误"并进行了无意义的 5 秒等待。最终那个请求等了整整 30 秒才超时，用户体验极差。
四大主流 AI API 错误码对照表
2.1 HTTP 状态码层（所有平台通用）
| 状态码 | 含义 | 所有平台通用吗 |
|---|---|---|
| 200 | 请求成功 | ✓ |
| 400 | 请求格式错误/参数无效 | ✓ |
| 401 | 认证失败 | ✓ |
| 403 | 权限不足/被禁止 | ✓ |
| 429 | 请求过于频繁 | ✓ |
| 500 | 服务器内部错误 | ✓ |
| 503 | 服务暂时不可用 | ✓ |
2.2 OpenAI 错误码详解
{
"error": {
"message": "You exceeded your current quota, please check your plan and billing details.",
"type": "insufficient_quota",
"code": "insufficient_quota",
"param": null,
"status": 429
}
}OpenAI 常见 error.type 值：
invalid_request_error- 请求格式错误，通常是 JSON 解析失败invalid_api_key- API Key 无效或已过期rate_limit_exceeded- 触发速率限制insufficient_quota- 账户配额耗尽server_error- OpenAI 侧服务器问题timeout- 请求超时（默认 60 秒）context_length_exceeded- Token 超出模型上限
2.3 Claude (Anthropic) 错误码详解
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Overly frequent requests. Reduce request frequency.",
"status": 429
}
}Claude 常见 error.type 值：
authentication_error- API Key 认证失败rate_limit_error- 触发速率限制（Claude Sonnet 4.5 的 RPM 限制较严格）invalid_request_error- 请求参数无效overloaded_error- Claude 服务过载internal_server_error- Anthropic 服务器错误
2.4 Gemini 错误码详解
{
"error": {
"code": 429,
"message": "Resource exhausted",
"status": "RESOURCE_EXHAUSTED",
"details": [{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "RATE_LIMIT_EXCEEDED",
"domain": "aiplatform.googleapis.com"
}]
}
}Gemini 常见 status 值：
INVALID_ARGUMENT- 参数无效或格式错误RESOURCE_EXHAUSTED- 超出配额或速率限制NOT_FOUND- 请求的资源不存在PERMISSION_DENIED- 权限不足INTERNAL- Google 服务器内部错误UNAVAILABLE- 服务暂时不可用
2.5 DeepSeek 错误码详解
{
"error": {
"message": "tokens usage limit exceeded",
"type": "invalid_request_error",
"code": "context_length_exceeded",
"status": 400
}
}DeepSeek 常见错误场景：
invalid_api_key- API Key 无效context_length_exceeded- Token 超出 DeepSeek V3.2 的上下文限制rate_limit_exceeded- DeepSeek 的免费用户 RPM 限制较严internal_server_error- DeepSeek 服务器错误（高峰期较常见）
我的实战：错误码统一处理架构
经历了那个双十一的惨痛教训后，我设计了一套统一的 AI API 错误处理框架。现在我们的电商 AI 客服系统接入了 HolySheheep AI 作为统一网关，配合我自研的错误处理中间件，实现了 99.9% 的请求成功率。
使用 HolySheheep 的核心优势在于：¥1=$1 无损汇率（官方 ¥7.3=$1），而且国内直连延迟 <50ms，对于高并发场景简直是救星。以下是我的统一错误处理代码：
import requests
import time
from typing import Optional, Dict, Any
from dataclasses import dataclass
from enum import Enum
class AIErrorType(Enum):
"""统一错误类型枚举"""
AUTH_ERROR = "auth_error" # 认证失败
RATE_LIMIT = "rate_limit" # 速率限制
QUOTA_EXCEEDED = "quota_exceeded" # 配额耗尽
INVALID_REQUEST = "invalid_request"# 请求无效
CONTEXT_LENGTH = "context_length" # 上下文超限
SERVER_ERROR = "server_error" # 服务器错误
TIMEOUT = "timeout" # 超时
UNKNOWN = "unknown" # 未知错误
@dataclass
class UnifiedAIError:
"""统一错误对象"""
error_type: AIErrorType
original_code: Optional[str]
message: str
retry_after: Optional[int] = None # 需要等待的秒数
should_retry: bool = True
class UnifiedAIErrorHandler:
"""统一错误处理器"""
# OpenAI 错误码映射
OPENAI_ERROR_MAP = {
"invalid_api_key": AIErrorType.AUTH_ERROR,
"incorrect_api_key": AIErrorType.AUTH_ERROR,
"invalid_request_error": AIErrorType.INVALID_REQUEST,
"rate_limit_exceeded": AIErrorType.RATE_LIMIT,
"insufficient_quota": AIErrorType.QUOTA_EXCEEDED,
"server_error": AIErrorType.SERVER_ERROR,
"timeout": AIErrorType.TIMEOUT,
"context_length_exceeded": AIErrorType.CONTEXT_LENGTH,
}
# Claude 错误码映射
CLAUDE_ERROR_MAP = {
"authentication_error": AIErrorType.AUTH_ERROR,
"rate_limit_error": AIErrorType.RATE_LIMIT,
"invalid_request_error": AIErrorType.INVALID_REQUEST,
"overloaded_error": AIErrorType.RATE_LIMIT,
"internal_server_error": AIErrorType.SERVER_ERROR,
}
# Gemini 状态码映射
GEMINI_STATUS_MAP = {
"UNAUTHENTICATED": AIErrorType.AUTH_ERROR,
"RESOURCE_EXHAUSTED": AIErrorType.RATE_LIMIT,
"INVALID_ARGUMENT": AIErrorType.INVALID_REQUEST,
"PERMISSION_DENIED": AIErrorType.AUTH_ERROR,
"INTERNAL": AIErrorType.SERVER_ERROR,
"UNAVAILABLE": AIErrorType.SERVER_ERROR,
}
@classmethod
def parse_openai_error(cls, response: Dict) -> UnifiedAIError:
"""解析 OpenAI 错误响应"""
error = response.get("error", {})
error_type_str = error.get("type", "unknown") or error.get("code", "unknown")
error_type = cls.OPENAI_ERROR_MAP.get(error_type_str, AIErrorType.UNKNOWN)
# 检查是否有 retry-after 头
retry_after = response.headers.get("retry-after")
return UnifiedAIError(
error_type=error_type,
original_code=error_type_str,
message=error.get("message", "Unknown error"),
retry_after=int(retry_after) if retry_after else None,
should_retry=error_type in [
AIErrorType.RATE_LIMIT,
AIErrorType.SERVER_ERROR,
AIErrorType.TIMEOUT
]
)
@classmethod
def parse_claude_error(cls, response: Dict) -> UnifiedAIError:
"""解析 Claude 错误响应"""
error = response.get("error", {})
error_type_str = error.get("type", "unknown")
error_type = cls.CLAUDE_ERROR_MAP.get(error_type_str, AIErrorType.UNKNOWN)
# 从消息中提取等待时间
retry_after = None
if error_type == AIErrorType.RATE_LIMIT:
# Claude 有时会返回 Retry-After 头
retry_after = 30 # 默认等待 30 秒
return UnifiedAIError(
error_type=error_type,
original_code=error_type_str,
message=error.get("message", "Unknown error"),
retry_after=retry_after,
should_retry=error_type in [
AIErrorType.RATE_LIMIT,
AIErrorType.SERVER_ERROR
]
)
@classmethod
def parse_gemini_error(cls, response: Dict) -> UnifiedAIError:
"""解析 Gemini 错误响应"""
error = response.get("error", {})
status = error.get("status", "UNKNOWN")
error_type = cls.GEMINI_STATUS_MAP.get(status, AIErrorType.UNKNOWN)
# 从 details 中提取更多信息
retry_after = None
for detail in error.get("details", []):
if detail.get("reason") == "RATE_LIMIT_EXCEEDED":
retry_after = 5 # Gemini 通常需要等待 5 秒
return UnifiedAIError(
error_type=error_type,
original_code=status,
message=error.get("message", "Unknown error"),
retry_after=retry_after,
should_retry=error_type in [
AIErrorType.RATE_LIMIT,
AIErrorType.SERVER_ERROR
]
)
@classmethod
def parse_by_http_status(cls, status_code: int, response: Dict,
provider: str) -> UnifiedAIError:
"""根据 HTTP 状态码和提供商类型解析错误"""
if provider == "openai":
return cls.parse_openai_error(response)
elif provider == "claude":
return cls.parse_claude_error(response)
elif provider == "gemini":
return cls.parse_gemini_error(response)
else:
# 默认处理
if status_code == 401:
return UnifiedAIError(
error_type=AIErrorType.AUTH_ERROR,
original_code=str(status_code),
message="Authentication failed",
should_retry=False
)
elif status_code == 429:
return UnifiedAIError(
error_type=AIErrorType.RATE_LIMIT,
original_code=str(status_code),
message="Rate limit exceeded",
retry_after=60,
should_retry=True
)
elif status_code >= 500:
return UnifiedAIError(
error_type=AIErrorType.SERVER_ERROR,
original_code=str(status_code),
message="Server error",
retry_after=5,
should_retry=True
)
else:
return UnifiedAIError(
error_type=AIErrorType.UNKNOWN,
original_code=str(status_code),
message=str(response),
should_retry=False
)上面这个错误处理类的核心思想是：将所有平台的错误统一映射为内部定义的 AIErrorType 枚举。无论上游是 OpenAI 的 rate_limit_exceeded，还是 Claude 的 rate_limit_error，在我的系统中都统一为 RATE_LIMIT，后续的重试逻辑、日志记录、告警通知都可以用同一套逻辑处理。
现在我们系统的完整调用代码如下（使用 HolySheheep API 作为统一网关）：
import requests
from typing import Optional, Dict, Any, Callable
import time
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
class AIRequestClient:
"""AI 请求客户端，支持 HolySheheep API 统一网关"""
def __init__(self, api_key: str, base_url: str = "https://api.holysheep.ai/v1"):
self.api_key = api_key
self.base_url = base_url
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
})
self.error_handler = UnifiedAIErrorHandler()
def chat_completion(
self,
messages: list,
model: str = "gpt-4.1",
temperature: float = 0.7,
max_tokens: int = 1000,
provider: str = "openai",
max_retries: int = 3,
callback: Optional[Callable] = None
) -> Dict[str, Any]:
"""
统一的聊天完成接口
Args:
messages: 消息列表
model: 模型名称 (gpt-4.1, claude-sonnet-4.5, gemini-2.5-flash, deepseek-v3.2)
temperature: 温度参数
max_tokens: 最大 token 数
provider: 提供商标识 (openai, claude, gemini, deepseek)
max_retries: 最大重试次数
callback: 错误发生时的回调函数
Returns:
API 响应结果
"""
endpoint = f"{self.base_url}/chat/completions"
payload = {
"model": model,
"messages": messages,
"temperature": temperature,
"max_tokens": max_tokens
}
last_error = None
for attempt in range(max_retries):
try:
response = self.session.post(
endpoint,
json=payload,
timeout=60
)
if response.status_code == 200:
return response.json()
# 解析错误
error_data = response.json() if response.text else {}
unified_error = self.error_handler.parse_by_http_status(
response.status_code,
error_data,
provider
)
# 记录错误日志
logger.warning(
f"Attempt {attempt + 1}/{max_retries} failed: "
f"{unified_error.error_type.value} - {unified_error.message}"
)
# 触发回调
if callback:
callback(unified_error)
# 不可重试的错误直接退出
if not unified_error.should_retry:
raise AIAPIError(unified_error)
# 计算等待时间
wait_time = unified_error.retry_after or (2 ** attempt)
logger.info(f"Waiting {wait_time} seconds before retry...")
time.sleep(wait_time)
last_error = unified_error
except requests.exceptions.Timeout:
last_error = UnifiedAIError(
error_type=AIErrorType.TIMEOUT,
original_code="timeout",
message="Request timeout after 60 seconds",
should_retry=attempt < max_retries - 1
)
logger.warning(f"Request timeout, attempt {attempt + 1}/{max_retries}")
time.sleep(2 ** attempt)
except requests.exceptions.RequestException as e:
last_error = UnifiedAIError(
error_type=AIErrorType.UNKNOWN,
original_code="request_exception",
message=str(e),
should_retry=False
)
logger.error(f"Request exception: {e}")
break
raise AIAPIError(last_error or UnifiedAIError(
error_type=AIErrorType.UNKNOWN,
original_code="max_retries_exceeded",
message="Max retries exceeded",
should_retry=False
))
class AIAPIError(Exception):
"""AI API 统一错误异常"""
def __init__(self, error: UnifiedAIError):
self.error = error
super().__init__(f"[{error.error_type.value}] {error.message}")
============ 使用示例 ============
def error_callback(error: UnifiedAIError):
"""错误回调函数 - 可用于发送告警"""
if error.error_type == AIErrorType.RATE_LIMIT:
print(f"🚨 触发速率限制，请检查账户配额")
elif error.error_type == AIErrorType.QUOTA_EXCEEDED:
print(f"🚨 账户配额耗尽，请及时充值")
elif error.error_type == AIErrorType.AUTH_ERROR:
print(f"🚨 认证失败，请检查 API Key")
初始化客户端
client = AIRequestClient(
api_key="YOUR_HOLYSHEEP_API_KEY", # 使用 HolySheheep API Key
base_url="https://api.holysheep.ai/v1"
)
发送请求 - 支持多种模型
try:
# 使用 GPT-4.1（$8/MTok）
result = client.chat_completion(
messages=[
{"role": "system", "content": "你是一个专业的电商客服"},
{"role": "user", "content": "双十一有什么优惠活动？"}
],
model="gpt-4.1",
provider="openai",
callback=error_callback
)
print(f"响应: {result['choices'][0]['message']['content']}")
except AIAPIError as e:
print(f"请求失败: {e}")
# 这里可以做降级处理，比如切换到备用模型或返回默认回复HolySheheep API 价格对比（2026年主流模型）
为什么我最终选择 HolySheheep 作为统一入口？让我们对比一下主流模型的价格：
| 模型 | 官方价格 | HolySheheep 价格 | 节省比例 |
|---|---|---|---|
| GPT-4.1 | $8.00/MTok | ¥8.00/MTok | 85%+ |
| Claude Sonnet 4.5 | $15.00/MTok | ¥15.00/MTok | 85%+ |
| Gemini 2.5 Flash | $2.50/MTok | ¥2.50/MTok | 85%+ |
| DeepSeek V3.2 | $0.42/MTok | ¥0.42/MTok | 85%+ |
以我们电商客服系统为例，月均 Token 消耗约 500M，如果使用 Claude Sonnet 4.5：
- 官方成本：$15 × 500 = $7,500/月
- HolySheheep 成本：¥15 × 500 = ¥7,500/月（约 $1,027）
- 节省：$6,473/月（86%）
而且 HolySheheep 支持微信/支付宝充值，国内开发者再也不用为信用卡支付烦恼。
常见报错排查
错误 1：401 Authentication Failed（认证失败）
# 错误响应示例
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key",
"status": 401
}
}
排查步骤：
1. 检查 API Key 是否正确复制（注意前后空格）
2. 确认 API Key 未过期或被撤销
3. 检查 base_url 是否正确（应该是 https://api.holysheep.ai/v1）
4. 确认 Authorization 头格式：Bearer YOUR_KEY
✅ 正确配置
headers = {
"Authorization": "Bearer sk-xxxxx",
"Content-Type": "application/json"
}
❌ 常见错误写法
headers = {
"Authorization": "sk-xxxxx", # 缺少 Bearer 前缀
"Content-Type": "application/json"
}错误 2：429 Rate Limit Exceeded（速率限制）
# 错误响应示例
{
"error": {
"message": "Too many requests in 1 minute. Please retry after 60 seconds.",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"status": 429
}
}
排查步骤：
1. 检查当前 RPM（每分钟请求数）是否超限
2. 查看响应头中的 X-RateLimit-Limit、X-RateLimit-Remaining
3. 实现请求队列和限流器
✅ 指数退避重试实现
def retry_with_backoff(func, max_retries=5):
for i in range(max_retries):
try:
return func()
except RateLimitError as e:
if i == max_retries - 1:
raise
wait_time = min(2 ** i, 60) # 最大等待 60 秒
print(f"Rate limited, waiting {wait_time}s...")
time.sleep(wait_time)
✅ 使用信号量控制并发
from threading import Semaphore
semaphore = Semaphore(10) # 最多 10 个并发请求
def throttled_request():
with semaphore:
return client.chat_completion(messages)错误 3：400 Invalid Request / context_length_exceeded（上下文超限）
# 错误响应示例
{
"error": {
"message": "This model's maximum context length is 128000 tokens...",
"type": "invalid_request_error",
"code": "context_length_exceeded",
"status": 400
}
}
排查步骤：
1. 计算当前消息列表的 token 数量
2. 确保不超过模型的最大上下文限制
3. 实现历史消息截断逻辑
✅ Token 计算辅助函数
def count_tokens(messages: list, model: str = "gpt-4.1") -> int:
"""估算 token 数量（简化版）"""
# 粗略估算：中文每个字符约 2 tokens，英文每个单词约 1.3 tokens
total = 0
for msg in messages:
# 系统提示
if msg.get("role") == "system":
total += 100 # 系统消息通常有固定开销
# 消息内容
content = msg.get("content", "")
# 中文字符
chinese_chars = sum(1 for c in content if '\u4e00' <= c <= '\u9fff')
# 其他字符
other_chars = len(content) - chinese_chars
total += chinese_chars * 2 + other_chars * 0.75
return int(total)
✅ 智能截断历史消息
def truncate_messages(messages: list, max_tokens: int, model: str) -> list:
"""截断历史消息以适应 token 限制"""
model_limits = {
"gpt-4.1": 128000,
"claude-sonnet-4.5": 200000,
"gemini-2.5-flash": 1000000,
"deepseek-v3.2": 64000
}
limit = model_limits.get(model, 128000)
# 保留 90% 用于输入，10% 预留给输出
available = int(limit * 0.9) - max_tokens
current_tokens = count_tokens(messages, model)
if current_tokens <= available:
return messages
# 从第二条消息开始逐条移除（保留首条 system 消息）
truncated = [messages[0]] # 保留系统提示
for msg in messages[1:]:
truncated.append(msg)
if count_tokens(truncated, model) <= available:
return truncated
return [messages[0]] # 只保留系统消息错误 4：500 Internal Server Error / Service Unavailable（服务器错误）
# 错误响应示例
{
"error": {
"message": "The server had an error while processing your request.",
"type": "server_error",
"code": "server_error",
"status": 500
}
}
排查步骤：
1. 检查上游服务商状态页面（OpenAI Status, Anthropic Status 等）
2. 查看是否是临时性故障
3. 实现自动降级策略
✅ 多后端降级实现
class FailoverClient:
def __init__(self):
self.backends = [
{"name": "holysheep", "base_url": "https://api.holysheep.ai/v1", "priority": 1},
{"name": "backup-1", "base_url": "...", "priority": 2},
{"name": "backup-2", "base_url": "...", "priority": 3},
]
self.current_backend = self.backends[0]
def request(self, payload: dict) -> dict:
for backend in self.backends:
try:
client = AIRequestClient(
api_key="YOUR_KEY",
base_url=backend["base_url"]
)
return client.chat_completion(**payload)
except (ServerError, ServiceUnavailable) as e:
print(f"Backend {backend['name']} failed: {e}")
continue
raise AllBackendsFailedError("All AI backends are unavailable")
✅ 健康检查与自动切换
def health_check():
"""定期检查后端健康状态"""
import threading
import time
def check_loop():
while True:
for backend in self.backends:
try:
client = AIRequestClient(base_url=backend["base_url"])
start = time.time()
client.session.get(f"{backend['base_url']}/models", timeout=5)
backend["latency"] = time.time() - start
backend["healthy"] = True
except:
backend["healthy"] = False
backend["latency"] = 999
# 选择最优后端
self.backends.sort(key=lambda x: (not x["healthy"], x["latency"]))
time.sleep(30)
thread = threading.Thread(target=check_loop, daemon=True)
thread.start()错误 5：网络超时（Connection Timeout / Read Timeout）
# 错误响应示例
requests.exceptions.ReadTimeout: HTTPAdapterPoolManager.post(...)
raised ReadTimeout(HTTPConnectionPool(host='api.holysheep.ai',
port=443): Read timed out. (read timeout=60))
排查步骤：
1. 确认是连接超时还是读取超时
2. 检查网络延迟（HolySheheep 国内 <50ms，如果很高说明网络问题）
3. 调整超时配置
✅ 合理的超时配置
client = AIRequestClient(api_key="YOUR_KEY")
设置连接超时和读取超时
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer YOUR_KEY",
"Content-Type": "application/json"
})
连接超时：建立连接的时间
读取超时：等待响应的时间
adapter = HTTPAdapter(
max_retries=Retry(
total=3,
backoff_factor=1,
status_forcelist=[500, 502, 503, 504]
),
pool_connections=10,
pool_maxsize=20
)
session.mount('https://', adapter)
✅ 分阶段超时配置
try:
response = session.post(
endpoint,
json=payload,
timeout=(5, 55) # (连接超时, 读取超时)
)
except requests.exceptions.ConnectTimeout:
print("无法连接到服务器，请检查网络")
except requests.exceptions.ReadTimeout:
print("服务器响应超时，可能是模型处理时间过长")
✅ 异步请求避免阻塞
import asyncio
import aiohttp
async def async_chat_completion(messages: list) -> str:
timeout = aiohttp.ClientTimeout(total=120, connect=10)
async with aiohttp.ClientSession(timeout=timeout) as session:
async with session.post(
"https://api.holysheep.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer YOUR_KEY",
"Content-Type": "application/json"
},
json={
"model": "gpt-4.1",
"messages": messages
}
) as response:
data = await response.json()
return data["choices"][0]["message"]["content"]
并发请求示例
async def batch_chat_completion(batch_messages: list) -> list:
tasks = [async_chat_completion(msgs) for msgs in batch_messages]
return await asyncio.gather(*tasks, return_exceptions=True)我的生产环境监控告警配置
仅仅有错误处理代码还不够，我建议在生产环境中配置完善的监控告警。以下是我的 Prometheus + Grafana 监控配置：
# Prometheus 告警规则
groups:
- name: ai_api_alerts
rules:
# 错误率告警
- alert: HighAIErrorRate
expr: |
sum(rate(ai_api_requests_total{status!="200"}[5m]))
/ sum(rate(ai_api_requests_total[5m])) > 0.05
for: 2m
labels:
severity: critical
annotations:
summary: "AI API 错误率超过 5%"
description: "当前错误率: {{ $value | humanizePercentage }}"
# 配额告警
- alert: AIQuotaWarning
expr: ai_api_quota_remaining / ai_api_quota_total < 0.1
for: 5m
labels:
severity: warning
annotations:
summary: "AI API 配额剩余不足 10%"
description: "模型: {{ $labels.model }}，剩余: {{ $value }}"
# 延迟告警
- alert: HighAILatency
expr: histogram_quantile(0.95, ai_api_latency_seconds) > 10
for: 5m
labels:
severity: warning
annotations:
summary: "AI API P95 延迟超过 10 秒"
description: "P95 延迟: {{ $value }}s"
# 速率限制告警
- alert: RateLimitFrequent
expr: |
sum(rate(ai_api_errors_total{error_type="rate_limit"}[1h]))
> 10
for: 10m
labels:
severity: warning
annotations:
summary: "速率限制频繁触发"
description: "过去 1 小时触发 {{ $value }} 次"
Grafana Dashboard JSON (关键 Panel 配置)
{
"panels": [
{
"title": "AI 请求成功率",
"type": "stat",
"targets": [{
"expr": "sum(ai_api_requests_total{status='200'}) / sum(ai_api_requests_total) * 100"
}],
"fieldConfig": {
"defaults": {
"unit": "percent",
"thresholds": {
"steps": [
{"value": 0, "color": "red"},
{"value": 95, "color": "yellow"},
{"value": 99, "color": "green"}
]
}
}
}
},
{
"title": "各模型 Token 消耗趋势",
"type": "timeseries",
"targets": [
{
"expr": "sum by (model) (rate(ai_api_tokens_total[1h]))",
"legendFormat": "{{model}}"
}
]
},
{
"title": "错误类型分布",
"type": "piechart",
"targets": [{
"expr": "sum by (error_type) (ai_api_errors_total)",
"legendFormat": "{{error_type}}"
}]
}
]
}总结：从失败到稳定的演进路径
回顾那个双十一