Hướng dẫn cốt lõi
Xử lý lỗi API
Đọc mã lỗi, chỉ thử lại khi cần thiết và lưu giữ Request ID
Xử lý lỗi dựa trên mã trạng thái HTTP và code. Trường message được viết cho người dùng và có thể thay đổi mà không cần thông báo trước.
Chat Completions và Responses sử dụng đối tượng error theo phong cách OpenAI. Anthropic Messages và Gemini giữ định dạng lỗi riêng của họ, vì vậy đừng sử dụng một trình phân tích cú pháp duy nhất cho mọi API của TokenLab.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Chỉ message và type luôn xuất hiện trong các lỗi tương thích với OpenAI do TokenLab tạo ra. Các trường khác chỉ xuất hiện khi chúng liên quan.
Mã trạng thái (Status codes)
| Trạng thái | Ý nghĩa | Hành động thông thường |
|---|---|---|
400 | Một trường, ID mô hình hoặc đầu vào không hợp lệ | Sửa yêu cầu; không lặp lại yêu cầu đó nếu chưa thay đổi |
401 | API key bị thiếu, không hợp lệ, hết hạn hoặc bị thu hồi | Thay thế bằng key mới |
402 | Số dư hoặc giới hạn của API key quá thấp | Nạp thêm tiền, nâng giới hạn hoặc giảm quy mô yêu cầu |
403 | Key này không thể sử dụng tài nguyên hoặc mô hình này | Thay đổi quyền của key hoặc chọn mô hình khác |
404 | Tài nguyên không tồn tại hoặc không còn khả dụng | Kiểm tra ID và API key đã tạo ra nó |
413 | Yêu cầu hoặc tệp tải lên quá lớn | Giảm đầu vào xuống giới hạn của mô hình hoặc endpoint đã ghi trong tài liệu |
429 | Đã đạt giới hạn yêu cầu | Chờ theo thời gian Retry-After |
500–504 | Dịch vụ không khả dụng hoặc lỗi mạng | Chỉ thử lại khi retryable là true; tuân thủ retry_after và giới hạn số lần thử |
Mã lỗi phổ biến
| Mã | Ý nghĩa | Những gì cần thay đổi |
|---|---|---|
invalid_api_key | Khóa API bị thiếu, không hợp lệ, không hoạt động hoặc đã bị thu hồi | Kiểm tra tiêu đề Authorization và giá trị key |
expired_api_key | Khóa API đã hết hạn | Tạo hoặc chọn một key đang hoạt động |
insufficient_balance | Số dư tài khoản không đủ để thực hiện yêu cầu | Nạp thêm tiền, giảm yêu cầu hoặc chọn mô hình có giá thấp hơn |
quota_exceeded | API key đã đạt giới hạn riêng | Tăng giới hạn của key đó hoặc sử dụng key được ủy quyền khác |
model_not_allowed | Key không thể sử dụng mô hình được yêu cầu | Cập nhật danh sách mô hình của key hoặc chọn mô hình được phép |
model_not_found | ID mô hình không xác định hoặc không khả dụng | Đọc /v1/models và sử dụng ID mô hình hiện tại |
context_length_exceeded | Đầu vào dài hơn mức mô hình chấp nhận | Xóa bớt lịch sử hoặc chọn mô hình có cửa sổ ngữ cảnh lớn hơn |
rate_limit_exceeded | Quá nhiều yêu cầu được gửi trong cửa sổ hiện tại | Chờ theo thời gian Retry-After |
payload_too_large | Nội dung yêu cầu hoặc tệp vượt quá giới hạn endpoint | Giảm hoặc nén đầu vào |
all_channels_failed | Mô hình đã chọn không thể xử lý yêu cầu này | Chỉ thử lại khi retryable là true; tuân thủ retry_after và giới hạn số lần thử |
timeout_error | Yêu cầu không hoàn thành kịp thời | Chỉ thử lại khi thao tác an toàn để lặp lại |
503 all_channels_failed hoặc 503 delivery_tier_unavailable không phải lúc nào cũng là lỗi tạm thời. Nếu không có nguồn cung cho thao tác trong cấp Delivery đã chọn, retryable là false và không trả về retry_after. Không lặp lại cùng một yêu cầu. Trước khi chọn mô hình khác, dùng GET /v1/models để kiểm tra khả năng cung cấp thao tác và Delivery. Tên tương tự không chứng minh tính khả dụng; các phương án thay thế chưa được xác minh sẽ bị bỏ qua.
Một số lỗi tương thích với OpenAI bao gồm các trường tùy chọn như did_you_mean, suggestions, alternatives, hint, retryable hoặc retry_after. Xem Các lỗi mà tác nhân có thể xử lý.
Khi yêu cầu chạy qua tuyến Official và dịch vụ upstream từ chối chính yêu cầu đó, chẳng hạn vì đầu vào không được chấp nhận hoặc quyết định chính sách nội dung, lỗi còn kèm upstream: message nguyên văn do upstream trả về, cùng code và source (tên dịch vụ upstream) khi biết. Lỗi của Anthropic Messages và Gemini mang cùng đối tượng này bên trong error của riêng chúng. Hãy tiếp tục phân nhánh theo code và type; giá trị upstream.code do dịch vụ upstream định nghĩa và có thể thay đổi.
Quyết định thử lại
| Lỗi | Có lặp lại cùng một yêu cầu không? |
|---|---|
400, 401, 402, 403, 404, 413 | Không. Hãy thay đổi yêu cầu, thông tin xác thực, số dư, quyền hoặc đầu vào. |
429 | Có, sau khoảng thời gian chờ do máy chủ cung cấp. |
500–504 | Chỉ thử lại khi retryable là true; tuân thủ retry_after và giới hạn số lần thử |
| Kết nối bị đóng trước khi có phản hồi | Đôi khi. Đối với các thao tác tạo, hãy kiểm tra xem tác vụ hoặc tác dụng phụ đã tồn tại chưa. |
| Luồng bị gián đoạn sau khi có đầu ra | Đừng coi đó là phản hồi hoàn chỉnh. Việc lặp lại có thể tạo ra đầu ra khác hoặc bị tính phí lần thứ hai. |
Đối với việc tạo hình ảnh, video, âm nhạc, 3D và Worlds, hãy lưu ID tác vụ ngay khi nó được trả về. Nếu yêu cầu tạo bị hết thời gian chờ (timeout), hãy kiểm tra bản ghi tác vụ trước khi gửi yêu cầu tạo khác.
Lưu giữ Request ID
Các tiêu đề phản hồi bao gồm Request ID để theo dõi. Hãy lưu nó cùng với endpoint, mô hình, thời gian và ID người dùng hoặc ID công việc của riêng bạn. Đối với công việc bất đồng bộ (async), hãy lưu thêm task_id và billing_transaction_id khi có.
Khi liên hệ với bộ phận hỗ trợ, hãy bao gồm các ID đó và một ví dụ đã được che thông tin nhạy cảm. Không bao giờ gửi API keys, management tokens, phương tiện riêng tư, signed URLs hoặc các lời nhắc (prompts) riêng tư hoàn chỉnh.