錯誤
任何 2xx 範圍以外的回應都帶有 JSON 內容。請針對 code 分支判斷，絕不要用 message —— 訊息是寫給人看的，措辭可能會改。
外層格式
{
"detail": {
"code": "INSUFFICIENT_BALANCE",
"message": "Add credits before deploying an instance",
"balance_microusd": 0,
"required_microusd": 2290000
}
}
| 鍵 | 型別 | 意義 |
|---|---|---|
detail.code | 字串 | 穩定、全大寫，可安全用來分支判斷 |
detail.message | 字串 | 一行的人類可讀說明 |
| 額外的鍵 | 依情況而定 | 該次特定失敗的脈絡資訊 |
有兩種失敗使用不同的格式。來自框架的請求驗證錯誤會在 detail 之下放一個清單，每個有問題的欄位一筆：
{"detail": [{"type": "greater_than_equal", "loc": ["body", "disk_gb"], "msg": "Input should be greater than or equal to 10"}]}
而非預期的伺服器端失敗則會在那裡放一個純字串，例如 {"detail": "Internal Server Error"}。如果你在寫用戶端函式庫，這三種形式都要處理。
HTTP 狀態
| 狀態 | 意義 |
|---|---|
| 200 | 請求成功 |
| 201 | 有東西被建立了 —— 執行個體、範本副本或 API 金鑰 |
| 204 | 成功但沒有內容：撤銷金鑰、刪除 SSH 金鑰 |
| 400 | 請求格式錯誤，例如 X-Org-Id 不是一個 id |
| 401 | bearer token 缺少、無效、已過期、已撤銷，或是在帳號端點上使用 API 金鑰 |
| 402 | 組織已無餘額 |
| 403 | 你通過了驗證但沒有權限：僅限管理員的動作、錯誤的組織，或不可變更的物件 |
| 404 | 找不到，或你的組織看不到 —— 這兩者刻意做成無法區分 |
| 409 | 狀態衝突：報價已被拿走、執行個體處於錯誤的狀態、名稱已被使用 |
| 422 | 值有問題：欄位超出範圍、硬碟大於機器容量、未知的列舉值 |
租用者真正會遇到的
| 情況 | 狀態 | 代碼 | 該怎麼做 |
|---|---|---|---|
| 在餘額為空時部署或啟動 | 402 | INSUFFICIENT_BALANCE | 由管理員在主控台儲值。回應內容帶有 balance_microusd 與 required_microusd。API 金鑰無法儲值。 |
| 報價在你列出清單到你部署之間被租走 | 409 | OFFER_UNAVAILABLE | 從你篩選出的清單取下一項報價再試。不要重試同一個 offer_id。 |
| 這台機器排定下線的時間，比啟動一個執行個體所需的時間還早 | 409 | MACHINE_IN_MAINTENANCE | 回應主體帶有 next_maintenance。換台機器部署，或等這段時段過去。這不是容量問題——機器上還有空閒的 GPU——所以時段結束後用同一項報價重試是可以的。 |
disk_gb 超出 10–20000 | 422 | 驗證清單 | 送出範圍內的值 |
disk_gb 大於主機的硬碟容量 | 422 | DISK_TOO_LARGE | 回應內容帶有 max_disk_gb。以該值或更低重試，或改挑更大的機器。 |
| 僅限管理員的動作，或用 API 金鑰嘗試任何管理員動作 | 403 | ADMIN_REQUIRED | 改用屬於管理員的工作階段權杖。結帳、邀請與成員管理永遠不開放給金鑰。請參閱角色與權限。 |
| 撤銷未知、已撤銷，或屬於別的組織的金鑰 | 404 | API_KEY_NOT_FOUND | 重新列出 GET /v1/api-keys 並使用目前有效的 id |
| 從不允許的狀態進行停止、啟動或銷毀 | 409 | INVALID_STATE | 先讀 status。訊息會指出目前的狀態，例如 Cannot start an instance while it is running。 |
在不支援 VM 的機器上使用 vm 範本 | 422 | OFFER_NOT_VM_CAPABLE | 篩選 vm_capable 為 true 的報價 |
不在你帳號上的 ssh_key_id | 404 | SSH_KEY_NOT_FOUND | 用工作階段權杖列出 GET /v1/ssh-keys，並從中挑一個 id |
| 你的組織看不到的執行個體、報價或範本 | 404 | INSTANCE_NOT_FOUND, OFFER_NOT_FOUND, TEMPLATE_NOT_FOUND | 檢查你送出的 X-Org-Id，以及該物件是否仍然存在 |
驗證與組織相關的失敗 —— TOKEN_INVALID、TOKEN_EXPIRED、NOT_A_MEMBER、ORG_MISMATCH、INVALID_ORG_ID —— 涵蓋在驗證。完整的代碼清單在錯誤代碼。
重試
| 回應 | 要重試嗎？ |
|---|---|
| 402 | 不要。在餘額進來之前什麼都不會變。 |
409 OFFER_UNAVAILABLE | 要，換一項報價。 |
409 MACHINE_IN_MAINTENANCE | 要，換一台機器；或等過了 next_maintenance 再用同一台。 |
409 INVALID_STATE | 只有在重新讀取執行個體、確認該轉換現在合法之後才重試。 |
| 422 | 不要。先把請求修好。 |
401 TOKEN_EXPIRED | 要，用新的工作階段權杖重試一次。shk_ 金鑰不會過期，所以金鑰收到 401 表示它被撤銷了。 |
POST /v1/instances 不接受冪等金鑰，所以逾時之後你無法確定租用到底成立了沒有。請用查詢解決，不要用重試： 呼叫 GET /v1/instances 並比對你的 label。
用同一個 offer_id 重試並不安全。一項報價是一種規格，不是單一個名額 —— 只要那台機器還有沒被租走的 GPU，同一項報價就會再答應你一次，於是一次本來只想部署一台的操作變成兩個分開計費的執行個體。要等到那台機器的單位用完，它才會回 409，而那正好是你本來就不會被重複收費的情況。