錯誤代碼 — TokSpan 文件

HTTP 狀態碼

代碼	含義	處理方式
400	錯誤請求	檢查請求主體中是否有格式錯誤的 JSON 或缺少必要欄位
401	未授權	確認您的 API 金鑰正確且在儀表板中為有效狀態
404	無效的 URL／找不到端點	對照 API 參考文件檢查請求路徑
429	速率限制／額度不足	針對速率限制，實作帶有抖動的指數退避。若錯誤提及額度或餘額（例如 `insufficient_user_quota`），請在儀表板中儲值，而非重試 — 請參閱速率限制
500	內部錯誤	TokSpan 端問題 — 使用退避策略重試或聯絡支援
502	錯誤閘道	上游供應商錯誤 — 自動容錯移轉可能啟動
503	服務不可用／找不到模型	暫時超載 — 以退避策略重試。若錯誤帶有 `model_not_found` 代碼，表示此金鑰無法使用該模型 — 請在模型目錄中檢查模型名稱

錯誤回應格式

錯誤以 error 物件返回，包含易讀的 message 與識別碼 type。在 TokSpan 上，type 通常是 new_api_error，而帳戶餘額錯誤會帶有 code: "insufficient_user_quota"。範例：

json
{
  "error": {
    "message": "You can access all models, but this request exceeded your account balance. Please top up at the Dashboard.",
    "type": "new_api_error",
    "param": null,
    "code": "insufficient_user_quota"
  }
}

閱讀訊息很重要。帶有速率限制訊息的 429 表示應退避並重試；帶有額度訊息的 429（或 400）則表示應先儲值。在決定如何應對前，請先閱讀訊息。此處顯示的訊息文字僅為示意 — 請一律以 HTTP 狀態碼與 code 欄位為準。