Common Error Solutions
Quickly locate and resolve common issues in LLM API usage, keeping your applications running stable
TroubleshootingUpdated: December 2024Important
🔍 Quick Diagnosis Tool
# Quick diagnosis script
curl -X POST https://api.n1n.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "test"}],
"max_tokens": 10
}' -w "\n\nHTTP Status: %{http_code}\nTime: %{time_total}s\n"
# Check points:
# 1. HTTP Status should be 200
# 2. Response time should be within a few seconds
# 3. Returns JSON formatted responseError Classification and Solutions
401 Unauthorized - 认证失败
错误信息
{
"error": {
"message": "Invalid authentication credentials",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
常见原因
- •API密钥错误或已过期
- •密钥前后有空格或特殊字符
- •using了错误的APIEndpoint
- •Authorization header格式错误
Solution
- 1. 检查API密钥是否正确, Note不要including 多余的空格
- 2. 确认密钥格式:
Bearer YOUR_API_KEY - 3. 在控制台重新Generate新的API密钥
- 4. 确认using正确的APIEndpointURL
# 正确的认证头格式
headers = {
"Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json"
}429 Too Many Requests - 速率限制
错误信息
{
"error": {
"message": "Rate limit reached. Please retry after 20 seconds.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
速率限制类型
RPM限制
每minutes请求数限制
TPM限制
每minutesToken数限制
Solution
import time
import random
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(
stop=stop_after_attempt(5),
wait=wait_exponential(multiplier=1, min=4, max=60)
)
def api_call_with_retry():
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello"}]
)
return response
except RateLimitError as e:
# 从响应头获取重试时间
retry_after = e.response.headers.get("Retry-After", 60)
print(f"Rate limited. Waiting {retry_after} seconds...")
time.sleep(int(retry_after))
raise # 让retry装饰器处理重试- • Implement指数退避重试Strategy
- • using请求队列控制并发
- • OptimizeTokenusing量
- • 考虑Upgrade到更高的using层级
Request Timeout - 请求超时
常见场景
- •Generate长文本内容时超时
- •网络延迟导致的超时
- •Model处理复杂任务超时
Solution
# 调整超时设置
import httpx
client = OpenAI(
api_key="YOUR_API_KEY",
timeout=httpx.Timeout(60.0, connect=5.0), # 60秒超时
max_retries=3 # 自动重试
)
# using流式响应避免超时
stream = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=messages,
stream=True # 流式响应
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")- • 增加客户端超时时间
- • using流式响应处理长内容
- • 减少max_tokensParameter
- • 分批处理大任务
400 Bad Request - Parameter错误
常见Parameter错误
Model不存在
错误: model_not_found
解决: 检查Model名称拼写, usingsupport的Model
消息格式错误
错误: invalid_message_format
解决: ensuremessages数组格式正确
Token超限
错误: context_length_exceeded
解决: 减少输入长度或usingsupport更长上下文的Model
# 正确的请求格式
{
"model": "gpt-3.5-turbo", // 正确的Model名
"messages": [
{
"role": "system", // 可选: 系统消息
"content": "You are a helpful assistant."
},
{
"role": "user", // 必需: 用户消息
"content": "Hello"
}
],
"temperature": 0.7, // 范围: 0-2
"max_tokens": 150, // 根据Model限制设置
"stream": false // 是否流式响应
}500 Internal Server Error - Service器错误
错误特征
- •通常是临时性错误
- •可能由Service器负载过高引起
- •重试通常能解决问题
Solution
# 智能重试Strategy
def safe_api_call(prompt, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}]
)
return response
except APIError as e:
if e.status_code >= 500 and attempt < max_retries - 1:
# Service器错误, 等待后重试
wait_time = (2 ** attempt) + random.uniform(0, 1)
print(f"Server error, retrying in {wait_time:.1f}s...")
time.sleep(wait_time)
else:
raise
return None- • 实施自动重试机制
- • using指数退避Strategy
- • 考虑using备用Endpoint
- • MonitorService状态页面
高级Debug技巧
完整的Error Handling和日志记录
import logging
import json
from datetime import datetime
from openai import OpenAI, APIError, RateLimitError, AuthenticationError
# Configure日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(levelname)s - %(message)s',
handlers=[
logging.FileHandler('api_errors.log'),
logging.StreamHandler()
]
)
class APIErrorHandler:
def __init__(self, client):
self.client = client
self.error_stats = {
'auth_errors': 0,
'rate_limits': 0,
'timeouts': 0,
'server_errors': 0,
'other_errors': 0
}
def handle_error(self, error, context=None):
"""统一的Error Handling"""
error_info = {
'timestamp': datetime.now().isoformat(),
'error_type': type(error).__name__,
'error_message': str(error),
'context': context
}
if isinstance(error, AuthenticationError):
self.error_stats['auth_errors'] += 1
logging.error(f"认证错误: {error}")
return {
'retry': False,
'message': '请检查API密钥Configure',
'action': 'CHECK_API_KEY'
}
elif isinstance(error, RateLimitError):
self.error_stats['rate_limits'] += 1
retry_after = error.response.headers.get('Retry-After', 60)
logging.warning(f"速率限制: 等待{retry_after}秒")
return {
'retry': True,
'wait_time': int(retry_after),
'message': f'速率限制, {retry_after}秒后重试',
'action': 'WAIT_AND_RETRY'
}
elif isinstance(error, APIError):
if error.status_code >= 500:
self.error_stats['server_errors'] += 1
logging.error(f"Service器错误: {error}")
return {
'retry': True,
'wait_time': 5,
'message': 'Service器错误, 稍后重试',
'action': 'RETRY_WITH_BACKOFF'
}
else:
self.error_stats['other_errors'] += 1
logging.error(f"API错误: {error}")
return {
'retry': False,
'message': f'请求错误: {error}',
'action': 'CHECK_REQUEST'
}
else:
self.error_stats['other_errors'] += 1
logging.error(f"未知错误: {error}")
return {
'retry': False,
'message': f'未知错误: {error}',
'action': 'CONTACT_SUPPORT'
}
def get_statistics(self):
"""获取错误统计"""
return self.error_stats
def safe_call(self, func, *args, **kwargs):
"""安全执行APICall"""
max_retries = kwargs.pop('max_retries', 3)
retry_count = 0
while retry_count < max_retries:
try:
result = func(*args, **kwargs)
logging.info(f"APICall成功")
return result
except Exception as e:
retry_count += 1
error_response = self.handle_error(e, {
'function': func.__name__,
'retry_count': retry_count,
'args': str(args)[:100]
})
if not error_response['retry'] or retry_count >= max_retries:
raise
wait_time = error_response.get('wait_time', 2 ** retry_count)
logging.info(f"等待{wait_time}秒后重试...")
time.sleep(wait_time)
raise Exception(f"达到最大重试次数: {max_retries}")
# usingExample
client = OpenAI(api_key="YOUR_API_KEY")
error_handler = APIErrorHandler(client)
try:
response = error_handler.safe_call(
client.chat.completions.create,
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello"}],
max_retries=5
)
print(response)
except Exception as e:
print(f"最终失败: {e}")
print(f"错误统计: {error_handler.get_statistics()}")问题诊断清单
基础检查
- API密钥是否正确?
- using正确的APIEndpoint?
- 请求格式是否正确?
- 网络连接是否正常?
Code检查
- Error Handling是否完善?
- 重试机制是否Implement?
- 超时设置是否合理?
- 日志记录是否完整?
🆘 need更多help?
如果问题仍未解决, 请through以下方式获取技术support
📧 邮件support
support@n1n.ai
24小时内回复
💬 在线客服
工作日 9:00-18:00
实时技术support
📚 Develop者社区
技术交流群
互助解决问题