Hướng dẫn cốt lõi
Các lỗi mà agent có thể xử lý
Sử dụng mã lỗi, thời gian thử lại và gợi ý từ model mà không cần phân tích văn bản
Trang này mô tả các lỗi API công khai có thể đọc được bằng máy dành cho các ứng dụng và coding agent. Trang này không cấp quyền truy cập vào các cuộc điều tra yêu cầu trong workspace hoặc hỗ trợ. Đối với một yêu cầu trong workspace của bạn, hãy bắt đầu với khắc phục sự cố yêu cầu.
Các lỗi TokenLab tương thích với OpenAI có thể bao gồm các gợi ý có cấu trúc cho agent hoặc ứng dụng. Hãy sử dụng các trường này khi chúng xuất hiện; đừng phân tích message (thông báo) ở dạng con người có thể đọc được để quyết định phải làm gì.
Các API Anthropic Messages và Gemini giữ nguyên định dạng lỗi gốc của chúng, vì vậy các phần mở rộng trên trang này chỉ áp dụng cho các lỗi Chat Completions và Responses tương thích với OpenAI.
Các trường lỗi tùy chọn
Tất cả các trường dưới đây xuất hiện bên trong đối tượng error và có thể không có.
| Trường | Kiểu dữ liệu | Cách sử dụng |
|---|---|---|
did_you_mean | string | Thay thế cho một model đã ngừng hoạt động, hoặc ID model khả dụng gần nhất |
suggestions | array | Các model có thể phù hợp với yêu cầu |
hint | string | Một giải thích ngắn gọn hoặc hành động được gợi ý |
retryable | boolean | Liệu cùng một yêu cầu có thể thành công sau đó hay không |
retry_after | number | Số giây cần chờ trước khi thử lại |
balance_usd | number | Số dư hiện tại bằng USD |
estimated_cost_usd | number | Chi phí ước tính của yêu cầu bị từ chối |
top_up_url | string | Liên kết trang thanh toán, xuất hiện trên một số lỗi insufficient_balance |
min_top_up_usd | number | Số tiền nạp tối thiểu bằng USD, xuất hiện trên một số lỗi insufficient_balance |
Client của bạn vẫn nên xử lý mọi lỗi dựa trên mã trạng thái HTTP và code. Hãy coi các trường bổ sung này là ngữ cảnh hữu ích, không phải là các trường bắt buộc.
Model không xác định
Một model bị viết sai chính tả hoặc không khả dụng sẽ trả về 400 model_not_found. Nếu did_you_mean xuất hiện, hãy hiển thị nó cho người dùng hoặc chỉ thử lại khi sản phẩm của bạn đã có quyền thay đổi model đã chọn.
{
"error": {
"message": "Model not found: please check the model name",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found",
"did_you_mean": "gpt-5.6-terra",
"suggestions": [
{"id": "gpt-5.6-terra"},
{"id": "gpt-5.6-luna"}
],
"hint": "Did you mean 'gpt-5.6-terra'? Use GET /v1/models to list all available models."
}
}Số dư không đủ
402 insufficient_balance có thể bao gồm số dư hiện tại và số tiền ước tính cần thiết, hoặc liên kết nạp tiền và số tiền nạp tối thiểu. Ứng dụng của bạn có thể cung cấp liên kết nạp tiền, một model ít tốn kém hơn hoặc một yêu cầu nhỏ hơn.
{
"error": {
"message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
"type": "insufficient_balance",
"code": "insufficient_balance",
"retryable": false,
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-5.6-luna"},
{"id": "deepseek-v4.1-flash"}
],
"hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
}
}Model không khả dụng
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 Delivery tier đã chọn, retryable sẽ là false và retry_after sẽ bị lược bỏ. Đừng lặp lại cùng một yêu cầu. Hãy kiểm tra thao tác và tính khả dụng của Delivery bằng GET /v1/models trước khi chọn model 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ị lược bỏ.
{
"error": {
"message": "This model is unavailable for the requested operation and Delivery tier.",
"type": "all_channels_failed",
"code": "all_channels_failed",
"retryable": false,
"hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
}
}Giới hạn tốc độ (Rate limit)
Đối với 429 rate_limit_exceeded, hãy đợi trong retry_after giây hoặc sử dụng tiêu đề phản hồi Retry-After tiêu chuẩn.
{
"error": {
"message": "Rate limit exceeded (1000/min for user role). Please retry later.",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
}
}Ngữ cảnh quá dài
Lỗi 400 context_length_exceeded không thể khắc phục bằng cách gửi lại cùng một yêu cầu. Hãy rút ngắn đầu vào hoặc để người dùng chọn một model có cửa sổ ngữ cảnh lớn hơn.
{
"error": {
"message": "This model's maximum context length is 128000 tokens...",
"type": "invalid_request_error",
"code": "context_length_exceeded",
"retryable": false,
"suggestions": [
{"id": "gemini-2.5-pro"},
{"id": "claude-sonnet-5"}
],
"hint": "Reduce your input or switch to a model with a larger context window."
}
}Tìm định dạng API phù hợp
Đọc tokenlab.accepted_request_formats từ GET /v1/models/{model} trước khi sử dụng API dành riêng cho model.
| Giá trị | Endpoint |
|---|---|
openai_chat_completions | /v1/chat/completions |
openai_responses | /v1/responses |
anthropic_messages | /v1/messages |
gemini_generate_content | /v1beta/models/{model}:generateContent |
Định dạng được chấp nhận xác nhận endpoint. Các công cụ và trường riêng lẻ vẫn có thể thay đổi tùy theo model; hãy kiểm tra trang model trước khi phụ thuộc vào chúng.
Tìm model theo tác vụ
Models API có thể trả về danh sách rút gọn hiện tại cho các tác vụ không phải trò chuyện:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image"Các giá trị recommended_for hợp lệ là image, video, music, 3d, tts, stt, embedding, rerank, translation và decision. Hãy gửi ID model đã chọn một cách rõ ràng trong yêu cầu tạo. TokenLab không tự động thay thế nó bằng một model khác.
Tổng quan có thể đọc được bằng máy
Các agent có thể đọc tổng quan API rút gọn tại:
GET https://api.tokenlab.sh/llms.txtNó bao gồm yêu cầu đầu tiên, các endpoint phổ biến, bộ lọc model và hướng dẫn xử lý lỗi.
Xử lý lỗi mà không cần phát lại yêu cầu
Ví dụ này thực hiện một yêu cầu, bảo toàn model đã chọn và báo cáo thông tin khôi phục có cấu trúc. Các lần thử lại của SDK bị vô hiệu hóa để ứng dụng của bạn có thể quyết định xem việc thử lại có an toàn hay không. Hãy trình bày các gợi ý model để người dùng lựa chọn rõ ràng; đừng tự động phát lại một thế hệ đã được chấp nhận hoặc đã hết thời gian chờ. Để thử lại một yêu cầu đã hết thời gian chờ một cách an toàn, hãy gửi nó kèm theo Idempotency-Key, như được hiển thị trong Thử lại an toàn với idempotency key.
import os
from openai import OpenAI, APIStatusError
with OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
) as client:
try:
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)
except APIStatusError as exc:
body = exc.body if isinstance(exc.body, dict) else {}
error = body.get("error", body)
if not isinstance(error, dict):
error = {}
print({
"status": exc.status_code,
"request_id": exc.request_id,
"code": error.get("code"),
"hint": error.get("hint"),
"suggested_model": error.get("did_you_mean"),
"retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
})
raise