Trong quá trình tích hợp AI API vào sản phẩm, việc xử lý lỗi là kỹ năng không thể thiếu. Bài viết này từ HolySheep AI sẽ giúp bạn nắm vững toàn bộ error code từ các nhà cung cấp hàng đầu, đồng thời so sánh hiệu quả chi phí khi sử dụng dịch vụ relay chính hãng.
Bảng So Sánh Chi Phí: HolySheep vs API Chính Thức
| Tiêu chí | API Chính Hãng | HolySheep AI | Relay Khác |
|---|---|---|---|
| Tỷ giá | ¥7.2 = $1 | ¥1 = $1 (tiết kiệm 85%+) | ¥5-6 = $1 |
| Thanh toán | Thẻ quốc tế | WeChat/Alipay | Limitado |
| Độ trễ | 80-150ms | <50ms | 100-200ms |
| Tín dụng miễn phí | Không | Có khi đăng ký | Không |
| GPT-4.1 | $15/MTok | $8/MTok | $12/MTok |
| Claude Sonnet 4.5 | $30/MTok | $15/MTok | $22/MTok |
| Gemini 2.5 Flash | $3.50/MTok | $2.50/MTok | $3/MTok |
| DeepSeek V3.2 | $1/MTok | $0.42/MTok | $0.80/MTok |
Tổng Quan Error Code AI API
Mỗi nhà cung cấp AI có hệ thống error code riêng. Tuy nhiên, chúng đều tuân theo nguyên tắc HTTP chuẩn và bổ sung thêm mã lỗi riêng.
OpenAI Error Code Chi Tiết
| Mã lỗi | HTTP Status | Mô tả | Nguyên nhân phổ biến |
|---|---|---|---|
| invalid_request_error | 400 | Yêu cầu không hợp lệ | Thiếu tham số bắt buộc, định dạng sai |
| invalid_api_key | 401 | API key không hợp lệ | Key sai, đã bị revoke, chưa kích hoạt |
| insufficient_quota | 429 | Hết quota | Tài khoản hết credits, giới hạn gói订阅 |
| rate_limit_exceeded | 429 | Vượt giới hạn tốc độ | Gửi quá nhiều request trong thời gian ngắn |
| server_error | 500 | Lỗi máy chủ OpenAI | Hệ thống bảo trì, quá tải |
| model_not_found | 404 | Model không tồn tại | Tên model viết sai, model đã ngừng hỗ trợ |
| context_length_exceeded | 400 | Vượt giới hạn context | Prompt quá dài so với limit của model |
| stream_error | 500 | Lỗi khi stream | Kết nối mạng không ổn định |
# Ví dụ xử lý lỗi OpenAI với HolySheep
import requests
import time
HOLYSHEEP_API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"
def call_openai_with_retry(messages, max_retries=3):
headers = {
"Authorization": f"Bearer {HOLYSHEEP_API_KEY}",
"Content-Type": "application/json"
}
payload = {
"model": "gpt-4.1",
"messages": messages,
"temperature": 0.7
}
for attempt in range(max_retries):
try:
response = requests.post(
f"{BASE_URL}/chat/completions",
headers=headers,
json=payload,
timeout=30
)
if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# Rate limit - đợi và thử lại
print(f"Rate limit hit, waiting 60s...")
time.sleep(60)
elif response.status_code == 401:
raise Exception("API key không hợp lệ")
elif response.status_code == 400:
error = response.json()
if "context_length" in error.get("error", {}).get("code", ""):
raise Exception("Prompt quá dài, cần giảm context")
raise Exception(f"Lỗi request: {error}")
else:
raise Exception(f"Lỗi server: {response.status_code}")
except requests.exceptions.Timeout:
if attempt < max_retries - 1:
time.sleep(2 ** attempt)
continue
raise Exception("Request timeout sau nhiều lần thử")
raise Exception("Đã thử tối đa số lần cho phép")
Sử dụng - chỉ cần thay endpoint, logic xử lý lỗi giữ nguyên
messages = [{"role": "user", "content": "Xin chào"}]
result = call_openai_with_retry(messages)
print(result["choices"][0]["message"]["content"])Anthropic Claude Error Code Chi Tiết
| Mã lỗi | HTTP Status | Mô tả | Giải pháp |
|---|---|---|---|
| authentication_error | 401 | Xác thực thất bại | Kiểm tra API key, xóa cache key cũ |
| permission_error | 403 | Không có quyền truy cập | Kiểm tra subscription, nâng cấp gói |
| rate_limit_error | 429 | Vượt rate limit | Giảm tần suất request, sử dụng batching |
| invalid_request_error | 400 | Request không hợp lệ | Kiểm tra định dạng request theo tài liệu |
| overloaded_error | 529 | Hệ thống quá tải | Đợi và thử lại sau, HolySheep có độ trễ <50ms |
| api_key_error | 401 | API key lỗi | Tạo key mới từ console |
| max_tokens_too_large | 400 | max_tokens vượt limit | Claude Sonnet 4.5 limit: 8192 tokens |
| invalid_version_error | 400 | Phiên bản API sai | Sử dụng "2023-06-01" hoặc mới nhất |
# Claude API với HolySheep - Xử lý lỗi toàn diện
import anthropic
import json
client = anthropic.Anthropic(
api_key="YOUR_HOLYSHEEP_API_KEY",
base_url="https://api.holysheep.ai/v1"
)
def generate_with_claude(prompt, max_tokens=1024):
try:
message = client.messages.create(
model="claude-sonnet-4.5",
max_tokens=max_tokens,
messages=[
{"role": "user", "content": prompt}
]
)
return message.content[0].text
except anthropic.APIStatusError as e:
# Xử lý theo status code
status = e.status_code
error_body = json.loads(e.response.text)
error_type = error_body.get("type", "")
error_msg = error_body.get("error", {}).get("message", "")
if status == 401:
print("❌ Lỗi xác thực: Kiểm tra API key")
# Log và thông báo admin
elif status == 403:
print("❌ Không có quyền: Kiểm tra subscription")
# Gợi ý nâng cấp tài khoản
elif status == 429:
print("⚠️ Rate limit: Đợi và thử lại")
# Implement exponential backoff
elif status == 529:
print("⚠️ Server quá tải: Thử lại sau 30s")
elif status == 400:
if "max_tokens" in error_msg:
print("❌ max_tokens vượt giới hạn model")
elif "context" in error_msg:
print("❌ Context quá dài, cần tóm tắt")
else:
print(f"❌ Request lỗi: {error_msg}")
raise e
except Exception as e:
print(f"❗ Lỗi không xác định: {str(e)}")
raise
Test với prompt dài
result = generate_with_claude(
"Phân tích xu hướng AI năm 2026 và dự đoán...",
max_tokens=2048
)
print(result)Google Gemini Error Code Chi Tiết
| Mã lỗi | HTTP Status | Mô tả | Cách xử lý |
|---|---|---|---|
| INVALID_ARGUMENT | 400 | Tham số không hợp lệ | Kiểm tra format request, tham số bắt buộc |
| UNAUTHENTICATED | 401 | Xác thực thất bại | API key hết hạn hoặc sai |
| PERMISSION_DENIED | 403 | Không có quyền | Kích hoạt API trong Google Cloud Console |
| RESOURCE_EXHAUSTED | 429 | Hết resource quota | Chờ reset quota, giảm tần suất |
| INTERNAL | 500 | Lỗi nội bộ Google | Thử lại với exponential backoff |
| DEADLINE_EXCEEDED | 408 | Request timeout | Tăng timeout, giảm độ phức tạp prompt |
| SAFETY | 400 | Nội dung bị chặn bởi safety filter | Điều chỉnh nội dung prompt |
| MODEL_NOT_FOUND | 404 | Model không tồn tại | Kiểm tra tên model chính xác |
# Gemini API với HolySheep
import requests
import json
HOLYSHEEP_API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"
def call_gemini(prompt, model="gemini-2.5-flash"):
"""Gọi Gemini qua HolySheep với xử lý lỗi đầy đủ"""
headers = {
"Authorization": f"Bearer {HOLYSHEEP_API_KEY}",
"Content-Type": "application/json"
}
# Gemini API format
payload = {
"contents": [{
"parts": [{"text": prompt}]
}],
"generationConfig": {
"temperature": 0.9,
"maxOutputTokens": 2048
}
}
try:
response = requests.post(
f"{BASE_URL}/models/{model}:generateContent",
headers=headers,
json=payload,
timeout=30
)
if response.status_code == 200:
result = response.json()
return result["candidates"][0]["content"]["parts"][0]["text"]
# Parse error response
error_data = response.json()
error = error_data.get("error", {})
error_code = error.get("code", "")
error_msg = error.get("message", "")
status = response.status_code
error_mapping = {
400: {
"INVALID_ARGUMENT": "Tham số không hợp lệ",
"SAFETY": "Nội dung bị chặn bởi safety filter",
"MODEL_NOT_FOUND": f"Model {model} không tồn tại"
},
401: {"UNAUTHENTICATED": "API key không hợp lệ"},
403: {"PERMISSION_DENIED": "Không có quyền truy cập API"},
429: {"RESOURCE_EXHAUSTED": "Đã vượt quota - thử lại sau"},
500: {"INTERNAL": "Lỗi server Gemini - thử lại sau"},
408: {"DEADLINE_EXCEEDED": "Request timeout - tăng timeout"}
}
if status in error_mapping:
for code, msg in error_mapping[status].items():
if code in str(error_data):
raise Exception(f"[{status}] {code}: {msg}")
raise Exception(f"Lỗi không xác định: {error_data}")
except requests.exceptions.Timeout:
raise Exception("Request timeout - Gemini phản hồi chậm")
except requests.exceptions.ConnectionError:
raise Exception("Lỗi kết nối - kiểm tra mạng")
Test
try:
result = call_gemini("Giải thích cơ chế attention trong Transformer")
print(result)
except Exception as e:
print(f"Error: {e}")DeepSeek Error Code Chi Tiết
| Mã lỗi | HTTP Status | Mô tả | Nguyên nhân |
|---|---|---|---|
| invalid_request | 400 | Request không hợp lệ | Thiếu tham số, format JSON sai |
| unauthorized | 401 | Chưa xác thực | API key trống hoặc sai |
| forbidden | 403 | Truy cập bị từ chối | IP bị block, key không có quyền |
| rate_limit_exceeded | 429 | Vượt rate limit | DeepSeek V3.2 có limit riêng |
| internal_server_error | 500 | Lỗi server | DeepSeek đang bảo trì |
| max_tokens_exceeded | 400 | Vượt max tokens | Tăng max_tokens hoặc giảm prompt |
| context_length_exceeded | 400 | Context quá dài | DeepSeek V3.2 limit: 64K tokens |
Lỗi Thường Gặp và Cách Khắc Phục
1. Lỗi 401 Unauthorized - API Key Không Hợp Lệ
Mô tả: Request bị từ chối với thông báo "Invalid API key" hoặc "API key is missing"
Nguyên nhân thường gặp:
- Copy paste API key bị thiếu ký tự đầu/cuối
- Sử dụng key từ môi trường khác (production vs development)
- Key đã bị revoke hoặc hết hạn
- Cache API key cũ trong code
# Cách khắc phục lỗi 401 - Kiểm tra và validate API key
import os
import requests
def validate_api_key(api_key):
"""Validate API key trước khi sử dụng"""
if not api_key:
raise ValueError("API key không được để trống")
# Kiểm tra format cơ bản
if len(api_key) < 20:
raise ValueError("API key quá ngắn - có thể bị cắt mất")
# Kiểm tra ký tự đặc biệt không hợp lệ
invalid_chars = ['\n', '\r', '\t', ' ']
for char in invalid_chars:
if char in api_key:
raise ValueError(f"API key chứa ký tự không hợp lệ: {repr(char)}")
return True
def test_connection():
"""Test kết nối với HolySheep"""
api_key = os.environ.get("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY")
try:
validate_api_key(api_key)
except ValueError as e:
print(f"❌ Validation thất bại: {e}")
return False
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
response = requests.get(
"https://api.holysheep.ai/v1/models",
headers=headers,
timeout=10
)
if response.status_code == 200:
print("✅ Kết nối thành công!")
models = response.json().get("data", [])
print(f"📦 Có {len(models)} models khả dụng")
return True
elif response.status_code == 401:
print("❌ Lỗi 401: API key không hợp lệ")
print("💡 Giải pháp: Kiểm tra lại API key trong HolySheep Dashboard")
return False
else:
print(f"⚠️ Lỗi khác: {response.status_code}")
return False
test_connection()2. Lỗi 429 Rate Limit - Vượt Giới Hạn Tốc Độ
Mô tả: Nhận được HTTP 429 với thông báo "Rate limit exceeded" hoặc "Too many requests"
Nguyên nhân thường gặp:
- Gửi quá nhiều request đồng thời
- Không implement exponential backoff
- Vượt TPM (tokens per minute) hoặc RPM (requests per minute)
- Không sử dụng batch processing khi cần
# Xử lý Rate Limit với Exponential Backoff
import time
import requests
from collections import defaultdict
from threading import Lock
class RateLimitHandler:
def __init__(self, base_delay=1, max_delay=60, max_retries=5):
self.base_delay = base_delay
self.max_delay = max_delay
self.max_retries = max_retries
self.request_counts = defaultdict(list)
self.lock = Lock()
def check_rate_limit(self, endpoint, limit=60, window=60):
"""Kiểm tra xem có nên gửi request không"""
current_time = time.time()
with self.lock:
# Xóa request cũ hơn window
self.request_counts[endpoint] = [
t for t in self.request_counts[endpoint]
if current_time - t < window
]
if len(self.request_counts[endpoint]) >= limit:
oldest = self.request_counts[endpoint][0]
wait_time = window - (current_time - oldest) + 1
return False, wait_time
self.request_counts[endpoint].append(current_time)
return True, 0
def make_request_with_backoff(self, url, headers, payload, model=None):
"""Gửi request với automatic backoff khi gặp rate limit"""
model = model or url
limit, window = self._get_limits(model)
for attempt in range(self.max_retries):
# Check rate limit trước
can_proceed, wait_time = self.check_rate_limit(model, limit, window)
if not can_proceed:
print(f"⏳ Rate limit sắp tới - đợi {wait_time:.1f}s...")
time.sleep(wait_time)
continue
try:
response = requests.post(url, headers=headers, json=payload, timeout=30)
if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# Parse retry-after header
retry_after = int(response.headers.get("Retry-After", 60))
print(f"⚠️ Rate limit hit - đợi {retry_after}s...")
time.sleep(retry_after)
continue
else:
raise Exception(f"HTTP {response.status_code}: {response.text}")
except requests.exceptions.Timeout:
if attempt < self.max_retries - 1:
delay = min(self.base_delay * (2 ** attempt), self.max_delay)
print(f"⏳ Timeout - thử lại sau {delay}s...")
time.sleep(delay)
continue
raise Exception("Request timeout sau nhiều lần thử")
raise Exception("Đã thử tối đa số lần cho phép")
def _get_limits(self, model):
"""Lấy rate limits theo model"""
limits = {
"gpt-4": (50, 60), # 50 RPM
"gpt-4.1": (50, 60),
"claude-sonnet-4.5": (40, 60), # 40 RPM
"gemini": (60, 60),
"deepseek-v3.2": (100, 60) # 100 RPM
}
return limits.get(model, (60, 60))
Sử dụng
handler = RateLimitHandler()
payload = {
"model": "deepseek-v3.2",
"messages": [{"role": "user", "content": "Test rate limit"}],
"temperature": 0.7
}
result = handler.make_request_with_backoff(
"https://api.holysheep.ai/v1/chat/completions",
{"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY"},
payload,
"deepseek-v3.2"
)
print("✅ Request thành công!")3. Lỗi Context Length Exceeded - Context Quá Dài
Mô tả: Error khi tổng tokens (prompt + response) vượt giới hạn của model
Nguyên nhân thường gặp:
- Prompt lịch sử chat quá dài
- File đính kèm quá lớn
- Không sử dụng chunking cho documents
- Tính toán tokens không chính xác
# Xử lý Context Length với Automatic Chunking
import tiktoken
class ContextManager:
"""Quản lý context length thông minh"""
MODEL_LIMITS = {
"gpt-4.1": 128000,
"gpt-4": 8192,
"gpt-3.5-turbo": 16385,
"claude-sonnet-4.5": 200000,
"gemini-2.5-flash": 1000000,
"deepseek-v3.2": 64000
}
# Buffer để dự phòng cho response
RESPONSE_BUFFER = 2048
def __init__(self, model="gpt-4.1"):
self.model = model
self.max_tokens = self.MODEL_LIMITS.get(model, 4096)
self.encoding = self._get_encoding()
def _get_encoding(self):
"""Lấy tokenizer phù hợp với model"""
if "claude" in self.model:
return None # Claude không cần tokenizer phía client
elif "gpt" in self.model:
return tiktoken.get_encoding("cl100k_base")
return tiktoken.get_encoding("cl100k_base")
def count_tokens(self, text):
"""Đếm số tokens trong text"""
if self.encoding:
return len(self.encoding.encode(text))
# Rough estimate: 4 chars ~= 1 token
return len(text) // 4
def truncate_messages(self, messages, max_response_tokens=1024):
"""Tự động cắt bớt messages để fit context"""
available = self.max_tokens - max_response_tokens - self.RESPONSE_BUFFER
# Tính tổng tokens hiện tại
total_tokens = 0
truncated_messages = []
for msg in reversed(messages):
msg_tokens = self.count_tokens(str(msg))
if total_tokens + msg_tokens <= available:
truncated_messages.insert(0, msg)
total_tokens += msg_tokens
else:
# Thêm system message nếu có
if truncated_messages and "role" in truncated_messages[0]:
continue
break
# Đảm bảo có ít nhất messages hiện tại
if not truncated_messages:
truncated_messages = [{"role": "user", "content": "Tiếp tục..."}]
return truncated_messages, total_tokens
def split_long_content(self, content, max_chunk_size=None):
"""Chia content dài thành chunks nhỏ hơn"""
max_chunk = max_chunk_size or (self.max_tokens // 4)
chunks = []
if self.encoding:
tokens = self.encoding.encode(content)
else:
tokens = content.split() # Fallback
current_chunk = []
current_tokens = 0
for token in tokens:
if current_tokens + 1 > max_chunk:
chunks.append(self._decode_tokens(current_chunk))
current_chunk = [token]
current_tokens = 0
else:
current_chunk.append(token)
current_tokens += 1
if current_chunk:
chunks.append(self._decode_tokens(current_chunk))
return chunks
def _decode_tokens(self, tokens):
"""Decode tokens về text"""
if self.encoding:
return self.encoding.decode(tokens)
return " ".join(tokens)
Sử dụng
manager = ContextManager("deepseek-v3.2")
messages = [
{"role": "system", "content": "Bạn là trợ lý AI"},
{"role": "user", "content": "Phân tích code sau..."},
]
Kiểm tra và truncate nếu cần
truncated, token_count = manager.truncate_messages(messages)
print(f"📊 Tokens: {token_count}/{manager.max_tokens}")
print(f"📝 Messages: {len(truncated)}")
Nếu content quá dài, chia thành chunks
if len(content) > 10000:
chunks = manager.split_long_content(content)
print(f"📦 Content chia thành {len(chunks)} chunks")4. Lỗi Stream Timeout - Kết Nối Bị Ngắt
Mô tả: Stream response bị timeout hoặc bị ngắt giữa chừng
Nguyên nhân thường gặp:
- Mạng không ổn định, đặc biệt từ Việt Nam sang server quốc tế
- Response quá dài vượt timeout
- Server bị quá tải
- Firewall chặn kết nối
# Xử lý Stream với Auto-reconnect
import requests
import json
import sseclient
import time
class StreamHandler:
"""Xử lý stream response với auto-reconnect"""
def __init__(self, api_key, base_url="https://api.holysheep.ai/v1"):
self.api_key = api_key
self.base_url = base_url
self.timeout = 120 # Timeout dài cho streaming
def stream_with_retry(self, messages, model="gpt-4.1", max_retries=3):
"""Stream response với automatic retry"""
headers = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json"
}
payload = {
"model": model,
"messages": messages,
"stream": True,
"temperature": 0.7
}
for attempt in range(max_retries):
try:
response = requests.post(
f"{self.base_url}/chat/completions",
headers=headers,
json=payload,
stream=True,
timeout=self.timeout
)
if response.status_code == 200:
return self._parse_stream(response)
elif response.status_code == 429:
wait_time = 30 * (attempt + 1)
print(f"⏳ Rate limit - đợi {wait_time}s...")
time.sleep(wait_time)
continue
elif response.status_code == 500:
if attempt < max_retries - 1:
print(f"⚠️ Server error - thử lại...")
time.sleep(5)
continue
else:
raise Exception(f"HTTP {response.status_code}")
except requests.exceptions.Timeout:
if attempt < max_retries - 1:
print(f"⏳ Timeout - reconnecting ({attempt + 1}/{max_retries})...")
time.sleep(2)
continue
raise Exception("Stream timeout sau nhiều lần thử")
except Exception as e:
if "connection" in str(e).lower():