Định dạng phản hồi lỗi
Tất cả lỗi trả về định dạng JSON nhất quán với tùy chọn gợi ý Agent-First:message, type, code, param) luôn tồn tại. Các trường gợi ý (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) là phần mở rộng tùy chọn để AI agent tự sửa. Xem Hướng dẫn Agent-First API để biết chi tiết.
Các endpoint tương thích OpenAI sử dụng các loại lỗi cổng ổn định của LemonData. Các endpoint tương thích Anthropic và Gemini sử dụng họ lỗi và cấu trúc phản hồi gốc của chúng.
Mã trạng thái HTTP
| Code | Description |
|---|---|
| 400 | Yêu cầu không hợp lệ - Tham số không hợp lệ |
| 401 | Không xác thực - API key không hợp lệ hoặc bị thiếu |
| 402 | Yêu cầu thanh toán - Số dư không đủ |
| 403 | Bị cấm - Từ chối truy cập hoặc model không được phép |
| 404 | Không tìm thấy - Model hoặc tài nguyên không tồn tại |
| 413 | Dữ liệu tải lên quá lớn - Vượt quá kích thước input hoặc file |
| 429 | Quá nhiều yêu cầu - Vượt quá giới hạn tốc độ |
| 500 | Lỗi máy chủ nội bộ |
| 502 | Bad Gateway - Lỗi từ nhà cung cấp thượng nguồn |
| 503 | Dịch vụ không khả dụng - Dịch vụ tạm thời không có |
| 504 | Gateway Timeout - Yêu cầu hết thời gian chờ |
Các loại lỗi
Lỗi xác thực (401)
| Type | Code | Description |
|---|---|---|
invalid_api_key | invalid_api_key | API key bị thiếu hoặc không hợp lệ |
expired_api_key | expired_api_key | API key đã bị thu hồi |
Lỗi thanh toán (402)
| Type | Code | Description |
|---|---|---|
insufficient_balance | insufficient_balance | Số dư tài khoản quá thấp (endpoint tương thích OpenAI) |
insufficient_balance_error | insufficient_balance | Số dư tài khoản quá thấp (endpoint tương thích Anthropic) |
quota_exceeded | quota_exceeded | Đã đạt giới hạn sử dụng API key |
Lỗi truy cập (403)
| Type | Code | Description |
|---|---|---|
access_denied | access_denied | Bị từ chối quyền truy cập tài nguyên |
access_denied | model_not_allowed | Model không được phép sử dụng với API key này |
Lỗi xác thực tham số (400)
| Type | Description |
|---|---|
invalid_request_error | Tham số yêu cầu không hợp lệ |
context_length_exceeded | Đầu vào quá dài cho model |
model_not_found | Model yêu cầu không có sẵn trong hợp đồng công khai hiện tại |
model_not_found.
Lỗi giới hạn tốc độ (429)
Khi bạn vượt quá giới hạn tốc độ:Retry-After và trường retry_after đều chỉ ra số giây chính xác cần chờ trước khi thử lại.
Dữ liệu tải lên quá lớn (413)
Khi kích thước input hoặc file vượt quá giới hạn:- File ảnh quá lớn (tối đa 20MB)
- File âm thanh quá lớn (tối đa 25MB)
- Văn bản đầu vào vượt quá độ dài ngữ cảnh của model
Lỗi thượng nguồn (502, 503)
| Type | Description |
|---|---|
upstream_error | Nhà cung cấp trả về lỗi |
all_channels_failed | Không có nhà cung cấp khả dụng |
timeout_error | Yêu cầu hết thời gian chờ |
Xử lý lỗi trong Python
Xử lý lỗi trong JavaScript
Thực hành tốt nhất
Áp dụng exponential backoff
Áp dụng exponential backoff
Khi bị giới hạn tốc độ, chờ ngày càng lâu hơn giữa các lần thử lại:
Đặt timeout
Đặt timeout
Luôn đặt timeout hợp lý để tránh các yêu cầu treo:
Ghi nhật ký lỗi để gỡ lỗi
Ghi nhật ký lỗi để gỡ lỗi
Ghi lại toàn bộ phản hồi lỗi bao gồm request ID để hỗ trợ:
Xử lý lỗi riêng cho từng model
Xử lý lỗi riêng cho từng model
Một số model có yêu cầu riêng (ví dụ: số token tối đa, định dạng ảnh).
Kiểm tra hợp lệ đầu vào trước khi thực hiện yêu cầu.