核心指南
處理 API 錯誤
讀取錯誤代碼、僅在必要時重試,並保留 Request ID
請根據 HTTP 狀態碼和 code 來處理錯誤。message 是為人類閱讀而編寫的,可能會隨時變更,恕不另行通知。
Chat Completions 和 Responses 使用 OpenAI 風格的 error 物件。Anthropic Messages 和 Gemini 則保留其各自的錯誤格式,因此請勿對所有 TokenLab API 使用單一解析器。
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}在 TokenLab 建立的 OpenAI 相容錯誤中,僅 message 和 type 是必定存在的。其他欄位僅在相關時才會出現。
狀態碼
| 狀態 | 含義 | 典型操作 |
|---|---|---|
400 | 欄位、模型 ID 或輸入無效 | 修復請求;請勿在未修改的情況下重複發送 |
401 | API key 遺失、無效、過期或已撤銷 | 更換 key |
402 | 餘額或 API-key 限額過低 | 儲值、提高限額或減少請求量 |
403 | 此 key 無法使用該資源或模型,或帳戶受到限制 | 更改 key 的權限或模型,或聯繫支援團隊 |
404 | 資源不存在或已無法使用 | 檢查 ID 以及建立該資源的 API key |
409 | Idempotency-Key 已被使用:請求主體不同 (idempotency_conflict),或 TokenLab 無法返回該請求的結果 (idempotency_replay_unavailable, idempotent_response_not_replayable)。TokenLab 未再次執行該請求 | 為新請求使用新的 key。若要決定是否使用相同的 key 重試,請參閱 使用 idempotency key 安全重試 |
413 | 請求或上傳的檔案過大 | 根據文件限制減少輸入至模型或端點的限制範圍 |
429 | 已達請求限額 | 等待 Retry-After |
500–504 | 服務不可用或網路故障 | 僅在 retryable 為 true 時重試;請遵守 retry_after 並限制嘗試次數 |
常見錯誤代碼
| 代碼 | 含義 | 應變措施 |
|---|---|---|
invalid_api_key | API key 遺失、無效、未啟用或已撤銷 | 檢查 Authorization 標頭和 key 值 |
expired_api_key | key 已過期 | 建立或選擇一個有效的 key |
insufficient_balance | 帳戶餘額不足以支付請求 | 儲值、減少請求量或選擇價格較低的模型 |
quota_exceeded | API key 已達其自身限額 | 提高該 key 的限額或使用其他已授權的 key |
model_not_allowed | key 無法使用所請求的模型 | 更新 key 的模型列表或選擇允許的模型 |
user_suspended, account_restricted | HTTP 403。帳戶無法使用 API | 提供 Request ID 並聯繫支援團隊 |
invalid_delivery_policy | HTTP 400。X-TokenLab-Delivery-Policy 標頭非 auto、verified 或 official | 發送這三個值之一,或移除該標頭 |
model_not_found | 模型 ID 未知或不可用 | 讀取 /v1/models 並使用當前的模型 ID |
context_length_exceeded | 輸入長度超過模型限制 | 移除歷史記錄或選擇具有更大上下文視窗的模型 |
missing_required_parameter | 缺少必要欄位。param 會標示該欄位,例如音訊和影像請求中的 model(無預設模型) | 發送 param 所標示的欄位 |
invalid_value | 欄位值不被模型接受,例如 reasoning_effort 值。訊息中會列出可接受的值 | 使用列出的值之一 |
invalid_response_format_type | HTTP 400。response_format 是物件但沒有可用的 type,或 type 取值不被此端點接受;param 為 response_format | 將 response_format.type 設為 text、json_object 或 json_schema;使用 json_schema 時還需送出 json_schema.name 與 json_schema.schema |
invalid_image_url | TokenLab 無法使用該影像 URL:它不是有效的 HTTP(S) URL 或影像資料 URI,或者影像主機未返回影像。param 會標示該欄位 | 發送公開的 HTTPS 影像 URL 或支援的資料 URI |
unsupported_model_capability | 所選 Delivery tier 的任何路徑皆不支援請求參數,例如操作、resolution、aspect_ratio、duration、輸入媒體欄位、web_search_options 或 max_tokens。訊息會列出每個不匹配的參數,若模型有發布,則會列出支援的值 | 移除或更改參數,或選擇其他 Delivery tier 或模型;請勿在未修改的情況下重複請求 |
unpriceable_selection | 影片請求遺漏了定價所需的選擇器,導致 TokenLab 無法計價。param 會標示該選擇器 | 設定 param 所標示的欄位 |
model_pricing_unavailable | HTTP 503。請求有效,但 TokenLab 無法在請求可使用的路徑上針對此模型與操作組合進行計價。請求未被扣款,且 retryable 為 false | 請勿在未修改的情況下重複請求;選擇其他模型或操作,或提供 Request ID 聯繫支援團隊 |
idempotency_conflict | HTTP 409。Idempotency-Key 屬於不同的請求。TokenLab 未執行此請求 | 使用新的 key 發送新請求 |
idempotency_replay_unavailable | HTTP 409。Idempotency-Key 已被使用,且 TokenLab 沒有可返回的結果。TokenLab 未再次執行此請求 | 若第一次請求可能仍在執行中,請等待並使用相同的 key 重試。否則請發送新的 key。請參閱 使用 idempotency key 安全重試 |
idempotent_response_not_replayable | HTTP 409。Idempotency-Key 屬於一個已完成任務的建立請求,且 TokenLab 無法返回原始的建立回應。回應主體頂層包含 task_id,位於 error 旁邊。TokenLab 未再次執行此請求 | 請勿使用此 key 重複請求。僅在需要新任務時才發送新的 key |
rate_limit_exceeded | 在當前視窗內發送了過多請求 | 等待 Retry-After |
all_channels_failed | 所選模型無法服務此請求 | 僅在 retryable 為 true 時重試;請遵守 retry_after 並限制嘗試次數 |
timeout_error | 請求未在時間內完成 | 僅在操作可安全重複時重試 |
503 all_channels_failed 或 503 delivery_tier_unavailable 不一定代表暫時性中斷。若所請求的操作在所選的 Delivery tier 中沒有供應,retryable 將為 false 且 retry_after 會被省略。請勿重複相同的請求。在選擇其他模型之前,請先使用 GET /v1/models 檢查操作和 Delivery 的可用性。名稱相似並不代表可用;未經驗證的替代方案將被省略。
部分 OpenAI 相容錯誤包含選用的 did_you_mean、suggestions、alternatives、hint、retryable 或 retry_after 欄位。請參閱 代理程式可採取的錯誤操作。
當請求在 Official 路徑上執行且上游服務拒絕該請求本身(例如輸入不被接受或內容政策決策)時,錯誤也會攜帶 upstream:即上游報告的 message,以及已知的 code 和 source(上游服務名稱)。Anthropic Messages 和 Gemini 錯誤在其自身的 error 內部攜帶相同的物件。請繼續根據 code 和 type 進行分支處理;upstream.code 的值由上游服務定義,可能會有所變更。
重試決策
| 錯誤 | 是否重複相同的請求? |
|---|---|
400, 401, 402, 403, 404, 413 | 否。請更改請求、憑證、餘額、權限或輸入。 |
429 | 是,在伺服器提供的延遲時間後。 |
500–504 | 僅在 retryable 為 true 時重試;請遵守 retry_after 並限制嘗試次數 |
| 連線在收到任何回應前中斷 | 是,當請求列於 使用 idempotency key 安全重試 且具有 Idempotency-Key 時:使用相同的 key 和主體再次發送。否則,請先檢查任務或副作用是否已存在。 |
| 串流在輸出到達後中斷 | 請勿將其視為完整回應。重複請求可能會產生不同的輸出或導致第二次扣款。 |
對於影像、影片、音樂、3D 和 Worlds 的建立,請在任務 ID 返回時立即儲存。如果建立請求逾時,請使用相同的 Idempotency-Key 和主體再次發送以獲取原始任務。若沒有 key,請在發送另一個建立請求前檢查任務記錄。
使用 idempotency key 安全重試
逾時或連線中斷無法告知您 TokenLab 是否已執行該請求。請在下方列出的請求中加入 Idempotency-Key 標頭。如此一來,重複發送相同的請求將不會導致二次執行或二次扣款。
- 每個操作請使用新的唯一值,例如 UUID。key 最多可包含 255 個字元。TokenLab 會忽略過長的 key,此時請求將失去 idempotency 保護:重試會導致再次執行並再次扣款。
POST /v1/messages/batches則不同:它會拒絕超過 256 個字元的 key 並返回400。 - 在發送請求前,請將 key 與您的作業記錄一併儲存。
- 重試時,請發送相同的 API key、相同的
Idempotency-Key以及相同的主體。 - 在收到除
409且代碼為idempotency_replay_unavailable以外的任何回應後,請勿再次使用該 key。請使用新的 key 發送任何新的嘗試。 - 關閉 SDK 重試功能 (
max_retries=0),以便由您的程式碼決定何時重複使用 key。
若沒有該標頭,每次重試都會被視為新的請求。
建立任務的請求
這些建立請求接受 Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generations, 和POST /v1/worlds/generations- 當返回任務時的
POST /v1/images/generations和POST /v1/images/edits - 帶有
"background": true的POST /v1/responses POST /v1/messages/batches
如果建立請求逾時,請在不進行任何更改的情況下再次發送。TokenLab 會返回原始建立請求的結果,且不會建立、分派或扣款第二次任務。通常結果是帶有相同 id 的原始任務(對於 Responses,則是原始回應物件),您可以繼續輪詢它。對於影片、音樂、3D、Worlds 和影像任務,結果也可能是第一次建立請求失敗時的原始錯誤。如果該任務已經完成且 TokenLab 沒有儲存建立回應,重試將返回 409 並帶有代碼 idempotent_response_not_replayable,且回應主體頂層包含 task_id。
如果您使用 TokenLab 已接受的 key 發送不同的主體,TokenLab 將拒絕該請求且不會建立任務。影片、音樂、3D 和 Worlds 的建立請求會返回 409 並帶有代碼 idempotency_conflict。Message Batches 會返回 409 並帶有錯誤類型 conflict_error。對於影像任務以及帶有 background: true 的 Responses 請求,此情況下的狀態碼和錯誤代碼不保證一致。請勿使用相同的 key 重試該請求。
Chat Completions, Responses, 和 Messages
POST /v1/chat/completions、不帶 background 的 POST /v1/responses 以及 POST /v1/messages 對於給定的 key 只會執行一次請求。使用相同 key 的重試會獲得以下結果之一:
| 情況 | 結果 |
|---|---|
| 第一次請求仍在執行中 | 409,代碼為 idempotency_replay_unavailable |
| 第一次請求在您的用戶端中斷後完成。請求未進行串流,結果為 1 MB 或更小,且您在 24 小時內使用相同主體重試 | 200,包含原始回應主體和標頭 Idempotent-Replayed: true。TokenLab 不會再次執行或扣款該請求 |
| key 以任何其他方式被使用,例如:您已收到結果、請求已進行串流、結果大於 1 MB,或已超過 24 小時 | 409,代碼為 idempotency_replay_unavailable |
| 主體與第一次請求不同 | 409,通常代碼為 idempotency_conflict。部分請求會返回 idempotency_replay_unavailable |
帶有上述任一代碼的 409 均表示 TokenLab 未再次執行該請求。帶有 key 的串流請求無法執行兩次,且 TokenLab 無法再次發送其輸出。
此範例會重試逾時的 Chat Completions 請求,並使用相同的 key 直到獲得結果:
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()) # 將此 key 與您的作業記錄一併儲存。
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 # 無回應:使用相同的 key 和主體重試。
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# 第一次嘗試可能仍在執行中。稍後的重試會返回其結果。
raise RuntimeError(f"No result for Idempotency-Key {key}")如果最後一次嘗試仍返回 idempotency_replay_unavailable,則 TokenLab 無法返回該結果。僅在第二次執行和第二次扣款皆可接受的情況下,才使用新的 key 發送請求。
保留 Request ID
回應標頭包含用於追蹤的 Request ID。請將其與端點、模型、時間以及您自己的使用者或作業 ID 一併儲存。對於非同步作業,若存在 task_id 和 billing_transaction_id,也請一併儲存。
聯繫支援團隊時,請提供這些 ID 和一個已遮蔽敏感資訊的範例。切勿發送 API keys、管理 token、私人媒體、簽名 URL 或完整的私人提示詞。