錯誤代碼一覽

處理策略請見錯誤處理策略。

索引

認證錯誤（401）

ERR_UNAUTHORIZED

Authorization 標頭缺少、格式錯誤，或帶有未知／已過期的 API 金鑰。

處理方式：確認金鑰值、確認金鑰未被停用，以及所呼叫的環境與金鑰核發的環境一致。

ERR_API_KEY_DISABLED

金鑰存在但已被停用。

處理方式：請管理員於 Studio 建立一把新金鑰。

授權錯誤（403）

• ERR_INVALID_SCOPE 表示金鑰缺少必要 scope，必定帶有 {required, available}。
• ERR_FORBIDDEN 表示 scope 無誤，屬於其他授權原因，由 details.reason 指明。

ERR_FORBIDDEN

{
  "error": {
    "code": "ERR_FORBIDDEN",
    "message": "This action requires step-up authentication",
    "details": { "reason": "step_up_required" },
    "request_id": "req_01j9f3k2m1"
  }
}

處理方式：依 details.reason 分支。step_up_required 須由 Studio 工作階段重新驗證（MFA）後重試。session_required 必須從 Studio 執行，任何金鑰皆無法達成。scope_escalation 只能要求呼叫者已持有的 scope。ip_not_allowed 請確認請求來自允許的網段。platform_managed 表示內建標準無法由客戶編輯；請內嵌自己的 scoring.rubric，或另建組織自有的評分標準。

ERR_INVALID_SCOPE

處理方式：建立一把具備所需 scope 的金鑰。

驗證錯誤（400）

ERR_VALIDATION_FAILED

請求內容或參數未通過驗證。

{
  "error": {
    "code": "ERR_VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      { "field": "responses[0].answer", "message": "Answer is required" }
    ],
    "request_id": "req_01j9f3k2m1"
  }
}

field 為出錯輸入的 JSON 路徑。

常見來源：提交缺少應作答的題目或參照重複、內容文件節點不合法、評分標準缺少零分級距或級距值重複、題目同時或皆未提供兩種評分標準形式。

處理方式：修正輸入。

ERR_INVALID_JSON

請求內容不是可解析的 JSON。

ERR_CONTENT_TOO_LONG

一份作答超過 5,000 字元（文字加數學原始碼）或 256 KB 序列化上限，詳見規格限制。

處理方式：修正輸入。

ERR_BATCH_TOO_LARGE

批次建立超過 100 筆。

處理方式：切分為多批送出。

ERR_PAYLOAD_TOO_LARGE

請求本體超過 10 MB（解壓縮後計算）。

處理方式：切分請求。

ERR_UNSUPPORTED_MEDIA_TYPE

帶有內容的請求使用了 application/json 以外的 Content-Type。

處理方式：設為 Content-Type: application/json（但 Content-Encoding 仍可以設定為 gzip）。

找不到（404）

ERR_NOT_FOUND

資源不存在，或 id 格式錯誤。

處理方式：檢查 id 及其前綴。

取得批閱結果時的 404 另有一種可能：作答仍為 pending 或 processing，version 1 尚未產生。此情形下 details.resource_type 為 "evaluation"。

狀態錯誤（409）

ERR_CONFLICT

該操作在資源目前狀態下不合法，或版本化寫入衝突。

處理方式：重新讀取資源後再行判斷。狀態衝突通常表示該操作已經完成，或必須自其他狀態開始。覆核版本衝突請見樂觀鎖，不應自動遞增版本重送。

ERR_DUPLICATE

要求唯一性的欄位與現存資源衝突。

處理方式：改用其他值，或以該值查詢既有資源。

ERR_DUPLICATE_TXID

冪等鍵在 24 小時內由不同的請求內容重複使用。

處理方式：不可視為成功。 若意圖確實是新的操作，請產生新的冪等鍵；若意圖確實為重送，則客戶端於兩次嘗試之間改動了 payload，應檢查並修正。

ERR_EXAM_LOCKED

寫入操作嘗試變更考試的題目清單。

處理方式：建立一份具備所需內容的新考試，原有考試繼續以它已接受的內容批閱。若意圖僅是修改標籤，請重送僅帶 name、description、custom_id、metadata 的 PATCH 請求。

ERR_EXAM_ARCHIVED

操作的目標是一份已封存的考試（例如對其建立提交）。

處理方式：取消封存使其回到 active，或改用另一份 active 的考試。

限流（429）

ERR_RATE_LIMIT_EXCEEDED

超過請求速率上限。回應同時帶有 Retry-After 與 X-RateLimit-* 標頭。

處理方式：至少等待 retry_after 秒後再以指數退避重試，並使用批次端點降低請求量。詳見限流與使用量。

批閱

批閱均為非同步請求：提交被受理（回應狀態 201）後，每筆作答將各自批閱。批閱執行後可能出現兩種結果：

• 批閱判定（blank、sensitive_content）不是錯誤，它們是批閱結果 outcome 欄位的值，而非 HTTP 錯誤代碼。作答會到達 completed（而非 failed），具備一筆分數為 0 的批閱結果，計入 summary.completed，並且可以被覆核。詳見 outcome 判定。
• 系統故障（ERR_TIMEOUT、ERR_INTERNAL）使作答停在終態 failed，且沒有批閱結果。非同步情形下，它們出現在 response.grading_failed webhook 的巢狀 error 物件之中。

ERR_TIMEOUT

處理超過時間上限。

非同步情形下，批閱在平台內部重試後仍逾時，作答被標記為 failed 且沒有批閱結果；同步情形下，請求超過處理窗口並回應 408。

處理方式：請以指數退避重試，POST 請求須沿用同一把 Idempotency-Key。若作答已是 failed，請於 Studio 重新排程。若持續逾時，請聯絡技術支援窗口 support@terathinker.com 並附上 request_id。

伺服器錯誤（5xx）

ERR_INTERNAL

非預期的伺服器錯誤，請求本身並無問題。

處理方式：採指數退避重試。若持續發生，請聯絡技術支援窗口 support@terathinker.com 並附上 request_id。

ERR_SERVICE_UNAVAILABLE

服務暫時無法使用（維護或過載），回應帶有 Retry-After 標頭。

處理方式：等待 Retry-After 秒後重試。

相關

• 錯誤處理策略 — 重試策略與客戶端樣板
• 規格限制