錯誤

任何 2xx 範圍以外的回應都帶有 JSON 內容。請針對 code 分支判斷，絕不要用 message —— 訊息是寫給人看的，措辭可能會改。

外層格式

{
  "detail": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Deploying needs about 1h of credit up front",
    "balance_micro": 1500000,
    "required_micro": 2305000
  }
}

鍵	型別	意義
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	狀態衝突：報價已被拿走、執行個體處於錯誤的狀態、名稱已被使用
410	已失效：邀請已被使用、已過期，或已被撤銷
413	請求主體超過端點接受的大小
422	值有問題：欄位超出範圍、硬碟大於機器容量、未知的列舉值
429	請求太多：請等待 Retry-After 指定的時間
503	暫時無法使用：主機無法完成的啟動，或目前無法執行的登入檢查。請稍後重試

租用者真正會遇到的

情況	狀態	代碼	該怎麼做
在餘額不足以支付組織加上該執行個體之後一小時的消耗（它的 GPU 與硬碟，加上執行中、啟動中或建立中執行個體的 GPU 與硬碟，以及已停止執行個體的硬碟）時部署或啟動——餘額為正並不夠	402	INSUFFICIENT_BALANCE	由管理員在主控台儲值。回應內容帶有 balance_micro 與 required_micro。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：不是你自己的，或 —— 用 team 金鑰時 —— 不是現任成員的	404	SSH_KEY_NOT_FOUND	用工作階段權杖列出 GET /v1/ssh-keys，並從中挑一個 id
組織裡已經有 25 個尚未銷毀的執行個體	409	INSTANCE_LIMIT_REACHED	回應內容帶有 limit。先銷毀一個——已停止與處於 error 的執行個體都算，所以停止空不出名額。
組織有一筆付款爭議尚未結案	402	PAYMENTS_FROZEN	在爭議結案之前，部署與啟動都會暫停。
範本尚未發布、鎖定的 CUDA 比機器的舊，或需要非 x86_64 硬體	422	TEMPLATE_COMING_SOON、TEMPLATE_CUDA_TOO_NEW、TEMPLATE_ARCH_UNSUPPORTED	部署之前，拿範本的 coming_soon 以及 constraints.cuda_max、constraints.arch 對照報價的 cuda_version 檢查一遍。
另一個組織的、從私有登錄庫拉取的範本，或其機器不為控制平面所知的報價	422、409	TEMPLATE_REQUIRES_OWNER、OFFER_NOT_PINNABLE	什麼都沒有被建立。用你自己的登錄庫憑證複製範本，或重新列出報價。
啟動一個主機無法接手的執行個體	409、503	HOST_UNREACHABLE、START_REFUSED、START_UNAVAILABLE	執行個體仍是 stopped。稍後重試——START_UNAVAILABLE 則是稍候即可。訊息表示主機已不再持有工作負載的 START_REFUSED 不會成功：銷毀後重新部署。
啟動一個 GPU 已被釋放（gpus_released）的執行個體，而另一位租用者正在使用其中一張	409	CAPACITY_UNAVAILABLE	執行個體仍是 stopped，硬碟還在。稍後重試；啟動必須取回同樣的 GPU，所以換別的機器或報價都不行。
同一個呼叫端的請求太多	429	RATE_LIMITED	等待 Retry-After 標頭中的秒數（回應主體裡也有 retry_after_s），再重試。
請求主體超過大小上限	413	PAYLOAD_TOO_LARGE	回應主體帶有 limit_bytes。送少一點：大多數端點為 1 MiB，範本為 4 MiB。
你的組織看不到的執行個體、報價或範本	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	不要。在餘額進來之前——如果是 PAYMENTS_FROZEN，則是在爭議結案之前——什麼都不會變。
409 INSTANCE_LIMIT_REACHED	只有在銷毀一個執行個體之後才重試。
409 OFFER_UNAVAILABLE	要，換一項報價。
409 MACHINE_IN_MAINTENANCE	要，換一台機器；或等過了 next_maintenance 再用同一台。
409 INVALID_STATE	只有在重新讀取執行個體、確認該轉換現在合法之後才重試——allowed_actions 會說明哪些合法。
409 HOST_UNREACHABLE、START_REFUSED、CAPACITY_UNAVAILABLE	稍後再試，並逐步拉長間隔。這段期間執行個體維持 stopped。
429 RATE_LIMITED	要，等 Retry-After 秒之後。
503	要，稍等一下之後。
422	不要。先把請求修好。遇到 INVALID_CURSOR 時，拿掉游標從頭列出。
401 TOKEN_EXPIRED	要，用新的工作階段權杖重試一次。shk_ 金鑰不會過期，所以金鑰收到 401 表示它被撤銷了。

POST /v1/instances 不接受冪等金鑰，所以逾時之後你無法確定租用到底成立了沒有。請用查詢解決，不要用重試： 呼叫 GET /v1/instances 並比對你的 label。

用同一個 offer_id 重試並不安全。一項報價是一種規格，不是單一個名額 —— 只要那台機器還有沒被租走的 GPU，同一項報價就會再答應你一次，於是一次本來只想部署一台的操作變成兩個分開計費的執行個體。要等到那台機器的單位用完，它才會回 409，而那正好是你本來就不會被重複收費的情況。