TokenLab

核心指南

處理 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 或輸入無效修復請求;請勿在未修改的情況下重複發送
401API key 遺失、無效、過期或已撤銷更換 key
402餘額或 API-key 限額過低儲值、提高限額或減少請求量
403此 key 無法使用該資源或模型,或帳戶受到限制更改 key 的權限或模型,或聯繫支援團隊
404資源不存在或已無法使用檢查 ID 以及建立該資源的 API key
409Idempotency-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_keyAPI key 遺失、無效、未啟用或已撤銷檢查 Authorization 標頭和 key 值
expired_api_keykey 已過期建立或選擇一個有效的 key
insufficient_balance帳戶餘額不足以支付請求儲值、減少請求量或選擇價格較低的模型
quota_exceededAPI key 已達其自身限額提高該 key 的限額或使用其他已授權的 key
model_not_allowedkey 無法使用所請求的模型更新 key 的模型列表或選擇允許的模型
user_suspended, account_restrictedHTTP 403。帳戶無法使用 API提供 Request ID 並聯繫支援團隊
invalid_delivery_policyHTTP 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_typeHTTP 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_urlTokenLab 無法使用該影像 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_unavailableHTTP 503。請求有效,但 TokenLab 無法在請求可使用的路徑上針對此模型與操作組合進行計價。請求未被扣款,且 retryable 為 false請勿在未修改的情況下重複請求;選擇其他模型或操作,或提供 Request ID 聯繫支援團隊
idempotency_conflictHTTP 409。Idempotency-Key 屬於不同的請求。TokenLab 未執行此請求使用新的 key 發送新請求
idempotency_replay_unavailableHTTP 409。Idempotency-Key 已被使用,且 TokenLab 沒有可返回的結果。TokenLab 未再次執行此請求若第一次請求可能仍在執行中,請等待並使用相同的 key 重試。否則請發送新的 key。請參閱 使用 idempotency key 安全重試
idempotent_response_not_replayableHTTP 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 或完整的私人提示詞。

從請求到調查與支援

本頁內容