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 response

Error 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. 1. 检查API密钥是否正确, Note不要including 多余的空格
  2. 2. 确认密钥格式: Bearer YOUR_API_KEY
  3. 3. 在控制台重新Generate新的API密钥
  4. 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者社区

技术交流群

互助解决问题