核心指南
代理程式可處理的錯誤
使用錯誤代碼、重試時間與模型建議,無需解析文字說明
本頁面說明供應用程式與編碼代理程式使用的機器可讀公開 API 錯誤。本頁面不提供工作區請求調查或支援的存取權限。若您的工作區有請求相關問題,請從 請求疑難排解 開始。
與 OpenAI 相容的 TokenLab 錯誤可能包含供代理程式或應用程式使用的結構化提示。當這些欄位存在時,請直接使用;請勿解析人類可讀的 message 來決定後續動作。
Anthropic Messages 與 Gemini API 會保留其原生的錯誤格式,因此本頁面的擴充功能僅適用於與 OpenAI 相容的 Chat Completions 與 Responses 錯誤。
選用錯誤欄位
下方所有欄位皆出現在 error 物件中,且可能不存在。
| 欄位 | 類型 | 用途 |
|---|---|---|
did_you_mean | string | 已停用模型的替代方案,或最接近的可用模型 ID |
suggestions | array | 可能適合該請求的模型 |
hint | string | 簡短說明或建議採取的行動 |
retryable | boolean | 相同的請求稍後是否可能成功 |
retry_after | number | 再次嘗試前需等待的秒數 |
balance_usd | number | 目前餘額(美元) |
estimated_cost_usd | number | 被拒絕請求的預估成本(美元) |
top_up_url | string | 帳單頁面連結,用於某些 insufficient_balance 錯誤 |
min_top_up_usd | number | 最低儲值金額(美元),用於某些 insufficient_balance 錯誤 |
您的客戶端仍應根據 HTTP 狀態碼與 code 來處理每個錯誤。請將這些額外欄位視為有用的上下文,而非必要欄位。
未知模型
拼寫錯誤或不可用的模型會回傳 400 model_not_found。如果 did_you_mean 存在,請將其顯示給使用者,或僅在您的產品已有權限變更所選模型時才進行重試。
{
"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."
}
}餘額不足
402 insufficient_balance 可能包含目前餘額與所需的預估金額,或是儲值連結與最低儲值金額。您的應用程式可以提供儲值連結、較便宜的模型或較小的請求。
{
"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."
}
}模型不可用
503 all_channels_failed 或 503 delivery_tier_unavailable 不一定代表暫時性中斷。如果所請求的操作在選定的 Delivery 層級中沒有供應,retryable 將為 false 且 retry_after 會被省略。請勿重複發送相同的請求。在選擇其他模型之前,請先使用 GET /v1/models 檢查該操作與 Delivery 的可用性。名稱相似並不代表可用;未經驗證的替代方案將被省略。
{
"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."
}
}速率限制
對於 429 rate_limit_exceeded,請等待 retry_after 指定的秒數,或使用標準的 Retry-After 回應標頭。
{
"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."
}
}上下文過長
400 context_length_exceeded 無法透過再次發送相同請求來解決。請縮短輸入內容,或讓使用者選擇具有更大上下文視窗的模型。
{
"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."
}
}尋找正確的 API 格式
在使用特定於模型的 API 之前,請先從 GET /v1/models/{model} 讀取 tokenlab.accepted_request_formats。
| 值 | 端點 |
|---|---|
openai_chat_completions | /v1/chat/completions |
openai_responses | /v1/responses |
anthropic_messages | /v1/messages |
gemini_generate_content | /v1beta/models/{model}:generateContent |
已接受的格式確認了端點。個別工具與欄位仍可能因模型而異;在依賴它們之前,請先檢查模型頁面。
依任務尋找模型
Models API 可以回傳非聊天任務的當前精選清單:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image"有效的 recommended_for 值包括 image、video、music、3d、tts、stt、embedding、rerank、translation 與 decision。請在建立請求時明確發送所選的模型 ID。TokenLab 不會自動將其替換為其他模型。
機器可讀概覽
代理程式可以在以下位置讀取精簡的 API 概覽:
GET https://api.tokenlab.sh/llms.txt其中包含首次請求、常見端點、模型篩選器與錯誤處理指南。
在不重播請求的情況下處理錯誤
此範例發出一個請求,保留所選模型,並回報結構化的復原資訊。SDK 重試功能已停用,以便您的應用程式可以決定重試是否安全。請提供模型建議以供明確選擇;請勿自動重播已接受或逾時的生成請求。若要安全地重試逾時的請求,請使用 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