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 trạng thái HTTP và code. Nội dung 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ữ các định dạng lỗi riêng của chúng, 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 là 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 sẽ xuất hiện khi chúng liên quan.
Mã trạng thái
| 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 gửi lại nếu chưa thay đổi |
401 | Thiếu API key, 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, tăng giới hạn hoặc giảm yêu cầu |
403 | Key này không thể sử dụng tài nguyên hoặc mô hình, hoặc tài khoản bị hạn chế | Thay đổi quyền của key hoặc mô hình, hoặc liên hệ bộ phận hỗ trợ |
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ó |
409 | Idempotency-Key đã được sử dụng: với nội dung yêu cầu khác (idempotency_conflict), hoặc cho một yêu cầu mà TokenLab không thể trả về kết quả (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab đã không thực hiện lại yêu cầu | Sử dụng key mới cho yêu cầu mới. Để quyết định xem có nên thử lại với cùng một key hay không, hãy xem Thử lại an toàn với idempotency key |
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 | Cần thay đổi gì |
|---|---|---|
invalid_api_key | API key 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 | Key đã 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 cho phép |
user_suspended, account_restricted | HTTP 403. Tài khoản không thể sử dụng API | Liên hệ bộ phận hỗ trợ kèm theo Request ID |
invalid_delivery_policy | HTTP 400. Tiêu đề X-TokenLab-Delivery-Policy không phải là auto, verified hoặc official | Gửi một trong ba giá trị này, hoặc xóa tiêu đề |
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 |
missing_required_parameter | Thiếu trường bắt buộc. param sẽ nêu tên trường đó, ví dụ model trong các yêu cầu âm thanh và hình ảnh, vốn không có mô hình mặc định | Gửi trường mà param đã nêu |
invalid_value | Một trường có giá trị mà mô hình không chấp nhận, ví dụ giá trị reasoning_effort. Thông báo sẽ liệt kê các giá trị được chấp nhận | Sử dụng một trong các giá trị được liệt kê |
invalid_response_format_type | HTTP 400. response_format là một object nhưng không có type dùng được, hoặc có type mà endpoint này không chấp nhận. param là response_format | Đặt response_format.type thành text, json_object hoặc json_schema; với json_schema, gửi thêm json_schema.name và json_schema.schema |
invalid_image_url | TokenLab không thể sử dụng URL hình ảnh: đây không phải là URL HTTP(S) hợp lệ hoặc URI dữ liệu hình ảnh, hoặc máy chủ hình ảnh không trả về hình ảnh. param sẽ nêu tên trường | Gửi URL hình ảnh HTTPS công khai hoặc URI dữ liệu được hỗ trợ |
unsupported_model_capability | Không có lộ trình nào của cấp Delivery đã chọn hỗ trợ tham số yêu cầu, chẳng hạn như thao tác, resolution, aspect_ratio, duration, trường phương tiện đầu vào, web_search_options hoặc max_tokens. Thông báo sẽ nêu tên từng tham số không khớp và, khi mô hình công bố chúng, các giá trị được hỗ trợ | Xóa hoặc thay đổi tham số, hoặc chọn cấp Delivery hoặc mô hình khác; không lặp lại yêu cầu mà không thay đổi |
unpriceable_selection | Yêu cầu video bỏ qua một bộ chọn mà giá của nó phụ thuộc vào đó, vì vậy TokenLab không thể định giá. param sẽ nêu tên bộ chọn | Thiết lập trường mà param đã nêu |
model_pricing_unavailable | HTTP 503. Yêu cầu hợp lệ, nhưng TokenLab không thể định giá sự kết hợp giữa mô hình và thao tác này trên các lộ trình mà yêu cầu có thể sử dụng. Yêu cầu không bị tính phí và retryable là false | Không lặp lại yêu cầu mà không thay đổi; chọn mô hình hoặc thao tác khác, hoặc liên hệ bộ phận hỗ trợ kèm theo Request ID |
idempotency_conflict | HTTP 409. Idempotency-Key thuộc về một yêu cầu khác. TokenLab đã không thực hiện yêu cầu này | Gửi yêu cầu mới với key mới |
idempotency_replay_unavailable | HTTP 409. Idempotency-Key đã được sử dụng và TokenLab không có kết quả để trả về cho nó. TokenLab đã không thực hiện lại yêu cầu này | Nếu yêu cầu đầu tiên vẫn có thể đang chạy, hãy đợi và thử lại với cùng một key. Nếu không, hãy gửi key mới. Xem Thử lại an toàn với idempotency key |
idempotent_response_not_replayable | HTTP 409. Idempotency-Key thuộc về một yêu cầu tạo đã hoàn thành tác vụ, và TokenLab không thể trả về phản hồi tạo ban đầu. Cấp cao nhất của nội dung phản hồi bao gồm task_id, bên cạnh error. TokenLab đã không thực hiện lại yêu cầu này | Không lặp lại yêu cầu với key này. Chỉ gửi key mới nếu bạn muốn một tác vụ mới |
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 |
all_channels_failed | Mô hình đã chọn không thể phục vụ 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 |
Lỗi 503 all_channels_failed hoặc 503 delivery_tier_unavailable không phải lúc nào cũng có nghĩa là sự cố tạm thời. Nếu thao tác được yêu cầu không có nguồn cung trong cấp Delivery đã chọn, retryable sẽ là false và retry_after bị bỏ qua. Không lặp lại cùng một yêu cầu. Kiểm tra thao tác và tính khả dụng của Delivery với GET /v1/models trước khi chọn mô hình khác. Các tên tương tự không chứng minh được tính khả dụng; các lựa chọ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 did_you_mean, suggestions, alternatives, hint, retryable hoặc retry_after. Xem Các lỗi mà agent có thể xử lý.
Khi một yêu cầu chạy trên lộ trình Official và dịch vụ thượng nguồn từ chối chính yêu cầu đó, chẳng hạn như đầu vào không được chấp nhận hoặc quyết định về chính sách nội dung, lỗi cũng sẽ mang theo upstream: message của thượng nguồn như đã báo cáo, cộng với code và source (tên dịch vụ thượng nguồn) khi được biết. Các lỗi của Anthropic Messages và Gemini mang cùng đối tượng đó bên trong error của riêng chúng. Hãy tiếp tục phân nhánh dựa trên code và type; các giá trị upstream.code được xác định bởi dịch vụ thượng nguồn và có thể thay đổi.
Quyết định thử lại
| Lỗi | Lặp lại cùng một yêu cầu? |
|---|---|
400, 401, 402, 403, 404, 413 | Không. 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 trễ 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 | Có, khi yêu cầu được liệt kê trong Thử lại an toàn với idempotency key và có Idempotency-Key: gửi lại với cùng key và nội dung. Nếu không, trước tiên 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 đầu ra đã đến | Đừng coi đó là một 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ờ, hãy gửi lại với cùng Idempotency-Key và nội dung để nhận tác vụ ban đầu. Nếu không có key, hãy kiểm tra bản ghi tác vụ trước khi gửi yêu cầu tạo khác.
Thử lại an toàn với idempotency key
Việc hết thời gian chờ hoặc kết nối bị đóng không cho bạn biết liệu TokenLab đã thực hiện yêu cầu hay chưa. Thêm tiêu đề Idempotency-Key vào các yêu cầu được liệt kê dưới đây. Khi đó, việc thử lại cùng một yêu cầu sẽ không thể chạy hoặc tính phí lần thứ hai.
- Sử dụng một giá trị duy nhất mới cho mỗi thao tác, ví dụ như UUID. Một key có thể có tối đa 255 ký tự. TokenLab bỏ qua key dài hơn, và yêu cầu đó sẽ không có bảo vệ idempotency: việc thử lại sẽ chạy và bị tính phí lần nữa.
POST /v1/messages/batchesthì khác: nó từ chối key dài hơn 256 ký tự với mã400. - Lưu key cùng với bản ghi công việc của riêng bạn trước khi gửi yêu cầu.
- Khi thử lại, hãy gửi cùng API key, cùng
Idempotency-Keyvà cùng nội dung. - Sau bất kỳ phản hồi nào khác ngoài
409vớiidempotency_replay_unavailable, đừng sử dụng lại key đó. Hãy gửi bất kỳ lần thử mới nào với một key mới. - Tắt tính năng thử lại của SDK (
max_retries=0), để mã của bạn quyết định khi nào nên sử dụng lại key.
Nếu không có tiêu đề, mỗi lần thử lại là một yêu cầu mới.
Các yêu cầu tạo tác vụ
Các yêu cầu tạo này chấp nhận Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generationsvàPOST /v1/worlds/generationsPOST /v1/images/generationsvàPOST /v1/images/editskhi chúng trả về một tác vụPOST /v1/responsesvới"background": truePOST /v1/messages/batches
Nếu yêu cầu tạo bị hết thời gian chờ, hãy gửi lại mà không thay đổi. TokenLab trả về kết quả của yêu cầu tạo ban đầu và không tạo, gửi hoặc tính phí tác vụ thứ hai. Thông thường kết quả là tác vụ ban đầu với cùng id (đối với Responses, là đối tượng phản hồi ban đầu), và bạn tiếp tục thăm dò nó. Đối với các tác vụ video, âm nhạc, 3D, Worlds và hình ảnh, kết quả cũng có thể là lỗi ban đầu khi yêu cầu tạo đầu tiên thất bại. Nếu tác vụ đó đã hoàn thành và TokenLab không có phản hồi tạo được lưu trữ, lần thử lại sẽ trả về 409 với mã idempotent_response_not_replayable, và cấp cao nhất của nội dung phản hồi bao gồm task_id.
Nếu bạn gửi nội dung khác với key mà TokenLab đã chấp nhận, TokenLab sẽ từ chối yêu cầu và không tạo tác vụ. Các yêu cầu tạo video, âm nhạc, 3D và Worlds trả về 409 với mã idempotency_conflict. Message Batches trả về 409 với loại lỗi conflict_error. Đối với các tác vụ hình ảnh và yêu cầu Responses với background: true, mã trạng thái và mã lỗi cho trường hợp này không được đảm bảo. Đừng thử lại yêu cầu với cùng một key.
Chat Completions, Responses và Messages
POST /v1/chat/completions, POST /v1/responses không có background và POST /v1/messages chỉ chạy yêu cầu với một key nhất định một lần. Việc thử lại với cùng key sẽ nhận được một trong các kết quả sau:
| Tình huống | Kết quả |
|---|---|
| Yêu cầu đầu tiên vẫn đang chạy | 409 với mã idempotency_replay_unavailable |
| Yêu cầu đầu tiên đã hoàn thành sau khi client của bạn ngắt kết nối. Yêu cầu không được truyền phát (streamed), kết quả từ 1 MB trở xuống và bạn thử lại với cùng nội dung trong vòng 24 giờ | 200 với nội dung phản hồi ban đầu và tiêu đề Idempotent-Replayed: true. TokenLab không chạy hoặc tính phí yêu cầu lần nữa |
| Key đã được sử dụng theo bất kỳ cách nào khác, ví dụ: bạn đã nhận được kết quả, yêu cầu đã được truyền phát, kết quả lớn hơn 1 MB hoặc đã quá 24 giờ | 409 với mã idempotency_replay_unavailable |
| Nội dung khác với yêu cầu đầu tiên | 409, thường với mã idempotency_conflict. Một số yêu cầu trả về idempotency_replay_unavailable |
Mã 409 với bất kỳ mã nào trong hai mã trên có nghĩa là TokenLab đã không thực hiện lại yêu cầu. Một yêu cầu được truyền phát với một key không thể chạy hai lần, nhưng TokenLab không thể gửi lại đầu ra của nó.
Ví dụ này thử lại yêu cầu Chat Completions bị hết thời gian chờ với cùng một key cho đến khi nhận được kết quả:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Lưu key này cùng với bản ghi công việc của bạn.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # Không có phản hồi: thử lại với cùng key và nội dung.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# Lần thử đầu tiên có thể vẫn đang chạy. Lần thử lại sau sẽ trả về kết quả của nó.
raise RuntimeError(f"No result for Idempotency-Key {key}")Nếu lần thử cuối cùng vẫn trả về idempotency_replay_unavailable, TokenLab không thể trả về kết quả đó. Chỉ gửi yêu cầu với key mới nếu việc chạy lần thứ hai và tính phí lần thứ hai là chấp nhận đượ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 không đồng bộ (async), hãy lưu cả task_id và billing_transaction_id khi có.
Khi liên hệ bộ phận hỗ trợ, hãy bao gồm các ID đó và một ví dụ đã được biên tập lại. Không bao giờ gửi API key, token quản lý, phương tiện riêng tư, URL đã ký hoặc các prompt riêng tư hoàn chỉnh.