錯誤碼對照表

通則

• 404 = 未授權或不存在。sandbox 刻意「不洩漏存在性」：沒權限、別家公司的 id、受限 key 動了禁區，全都回 404 而非 403。
• 403 是真實例外，不是預設。 建立呼叫者不能擁有的 department／company 任務 → owner_scope_forbidden。Writeback 發布／提交閘與預算 hold 也是 403。送 owner_scope=chatroom 是 422，不是 403。
• 422 = 請求驗證。未知欄位（extra="forbid"）、pattern 不符、大小超限、缺必帶 header。預算／hold 定價拒絕也可能是 422。
• 409 = 狀態衝突。非法狀態轉換、樂觀鎖 CAS 不符、digest 不符、不可重試、版本容量耗盡。
• 413 = body 過大。提交執行時依 Content-Length 先擋。
• 503 = kill switch。SANDBOX_ENABLED=false 時的變更（預設 true）。

對照表

Secret 傳輸加密錯誤（回應形狀不一樣）

POST /secrets 與 POST /secrets/rotate 用 pydantic model validator 驗證 encrypted_value，所以這四個不是本頁其他地方那種 {"detail": {"code": "..."}} 形狀——它們回的是 FastAPI 標準的驗證錯誤陣列，slug 在 detail[].type（也會鏡射進 detail[].msg，精確等於 validation_error:<slug>，input／ctx 會從回應裡剝除）：

四個都是 HTTP 422。Client 端加密流程見 Secret 與授權。

不是 REST 錯誤：share_grant_revoked

share_grant_revoked（409）只會出現在 runner 呼叫的控制面 manifest 揭露路由上——絕不會出現在 /private/module/sandbox 的租戶端點。當一個 owner 出借的 secret pin，其分享 grant 在 run 認領之後、到後續某次 manifest 讀取之間死掉了（撤銷、重新分享成新 generation、或 authority 變動），就會觸發這個。前端不會直接收到這個代碼，只會看到對應的 run 以失敗終結。見 Secret 與授權。

不在 /private/module/sandbox 底下：command-output 端點（v5.21.0）

POST /public/module/custom_tables/callback/command-output/{token_id} 是 Command 輸出 run 的 work script 拿密封憑證去呼叫的公開端點。它回 {"detail": {"code": "..."}}：404 output_run_unavailable（憑證不存在，或 Bearer secret 錯誤／缺少）、409 output_run_unavailable（憑證已撤銷或過期、run 已不在進行中，或它的任務或版本不再是 active 且已發布）、409 output_command_stale、409 output_command_conflict、422 output_schema_violation、403 output_policy_author_denied；body 格式不對或 token_id 不是 UUID 時，則是 FastAPI 的 422 validation 陣列，Command 執行本身也可能帶來它自己的錯誤。各代碼的意義見任務輸出交給自訂表格 Command。

Agent 工具錯誤（非 REST）

五個工具回 { "status": "error", "error": "<code>", "message": "..." }：

見 Agent toolkit。

前端處理建議

• 404：別假設是「不存在」——先確認權限、公司、key scope、id 是否屬於當前使用者。
• 403 owner_scope_forbidden：換一個呼叫者能擁有的 scope，或換有該 scope 管理權的人。
• 403 budget_reservation_exceeded：公司配額蓋不住這次 envelope；提示額度，不要重送同一請求。
• 422 缺 header：補 Idempotency-Key（每次新意圖用新 UUID，重試沿用）。
• 409：重新讀取資源目前 state 再決定下一步（別盲目重送）。
• 409 version_allocation_exhausted：沒有已確認的區域配額或 cap 為 0——這是營運／配額問題，不是租戶少填欄位。
• 503 sandbox_disabled：kill switch 關掉了（SANDBOX_ENABLED=false；預設開）。提示使用者稍後再試，取消/下載仍可用。
• 418：Authorization 與 X-Api-Key 都沒帶（共用 TeamSync credential 例外，Could not validate credentials，發生在 sandbox 404 隱藏之前）——不是 401；見認證。
• 租戶面的 429：sandbox_queued_run_limit、queue_full（地端；遵守 Retry-After）、staging_slot_exhausted、upload_rate_limited。退避；不要對 init 空轉重試。503 以外的 5xx 是平台失敗——退避重試；除非你還握著 Idempotency-Key，否則不要假設 run 沒建出來。

v5.10.0 新增的驗證與重試情況

• 422 detail[].type = sandbox_value_too_short：create／rotate 解密後少於 4 個 UTF-8 bytes。
• 409 task_version_not_published：明確 secret 核准指向未發布版本。
• 409 retry_input_unavailable：無法重放保留的來源 input，請傳明確 input。
• 核准 slot 集合非法／空白，或作者宣告使用保留 slot 名稱時，回 422 驗證錯誤。

請使用目前 OpenAPI 的 wait_reason、error_code、failure_stage 與 failure_source 型別。Provider 拒絕在重試處理後仍保留實際且已遮罩的來源資訊，不要自行轉成沒有內容的成功狀態。