錯誤碼對照表
通則
- 404 = 未授權或不存在。sandbox 刻意「不洩漏存在性」：沒權限、別家公司的 id、受限 key 動了禁區，全都回 404 而非 403。
- 422 = 請求驗證。未知欄位（
extra="forbid"）、pattern 不符、大小超限、缺必帶 header。 - 409 = 狀態衝突。非法狀態轉換、樂觀鎖 CAS 不符、digest 不符、不可重試。
- 413 = body 過大。提交執行時依
Content-Length先擋。 - 503 = kill switch。
SANDBOX_ENABLED=false時的變更。
對照表
| 狀態碼 | 錯誤 / 情境 | 何時發生 |
|---|---|---|
| 404 | 未授權 / 跨公司 / 受限 key 動禁區 / 資源不存在 | 幾乎所有授權失敗 |
| 404 | 產出物 deletion_state != active 的 download | 下載已刪/墓碑產出物 |
| 422 | idempotency_key_required | 提交/重試/quick-run/secret 寫入缺 Idempotency-Key |
| 422 | 欄位驗證 | 未知欄位、source_digest pattern、canonical JSON 超限、大小超限 |
| 413 | request_too_large | 提交執行 body 依 Content-Length 過大 |
| 400 | invalid_content_length | Content-Length header 不合法 |
| 409 | build_not_eligible | 版本 state 無法開始建置 |
| 409 | （取消不可取消狀態） | 取消一個非可取消的建置/執行 |
| 409 | retry_not_eligible | 重試一個非可重試終態的 run |
| 409 | task_version_digest_mismatch | secret 授權的 digest 與已發布版本不符 |
| 409 | （非法狀態轉換 / CAS） | 發布/歸檔非法轉換；policy_version CAS 不符 |
| 409 | （版本不可執行） | 提交執行時版本非 published+content active（_refuse_not_runnable） |
| 503 | sandbox_disabled | kill switch 下的變更（/cancel、/download 除外） |
| 503 | （secret adapter/pepper 不可用） | secret 寫入時後端相依不可用 |
Agent 工具錯誤（非 REST）
SandboxAgentConfirmError：validation_error、forged_receipt（receipt 非簽章多段格式）、not_found（過期/他人 receipt）、internal_error。詳見 Agent 確認流程。
前端處理建議
- 404：別假設是「不存在」——先確認權限、公司、key scope、id 是否屬於當前使用者。
- 422 缺 header：補
Idempotency-Key（每次新意圖用新 UUID，重試沿用）。 - 409：重新讀取資源目前 state 再決定下一步（別盲目重送）。
- 503
sandbox_disabled：模組被關；提示使用者稍後再試，取消/下載仍可用。
Last updated on