錯誤

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

外層格式

{
  "detail": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Deploying needs about 1h of credit up front for this and the organization's other instances",
    "balance_micro": 0,
    "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 金鑰無法儲值。
組織裡尚未銷毀的執行個體已達 25 個 —— stopped 與 error 的也算	409	INSTANCE_LIMIT_REACHED	回應內容帶有 limit。先銷毀不再需要的執行個體，包括處於 error 的，再部署。
報價在你列出清單到你部署之間被租走，或就在你的部署預留的那一刻被另一次部署拿走	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 的報價
範本被標記為即將推出（映像檔尚未發布）	422	TEMPLATE_COMING_SOON	換一個範本。GET /v1/templates 會列出這類範本，但它們無法部署。
範本鎖定了較舊的 CUDA 堆疊（cuda_max），而機器的 CUDA 版本較新	422	TEMPLATE_CUDA_TOO_NEW	換一台 cuda_version 不超過範本上限的機器，或換一個範本
範本宣告了 x86_64 以外的架構	422	TEMPLATE_ARCH_UNSUPPORTED	Superheat 的機器都是 x86_64。改用 x86_64 映像檔的範本。
別的組織的範本，從帶有憑證的私有登錄庫拉取	422	TEMPLATE_REQUIRES_OWNER	只有擁有它的組織能部署。把它複製到你的組織並填入你自己的登錄庫憑證（前提是你有權拉取那個映像檔）。什麼都沒有被建立。
報價所在的機器沒有在機群控制平面登記	409	OFFER_NOT_PINNABLE	清單不會顯示這類報價，通常是拿著舊的 offer_id。重新列出報價另挑一項。什麼都沒有被建立。
啟動一個 GPU 被釋放過的執行個體，而原來那幾張正被別人使用，或者在那台機器上已停止服務	409	CAPACITY_UNAVAILABLE	執行個體仍然是 stopped，硬碟完好，但啟動成功之前拿不到硬碟上的資料。稍後重試，這段期間照樣收儲存費用。一直不成功的話，唯一的出路是銷毀執行個體後重新部署——銷毀會把硬碟連同資料一起刪除。
啟動一個主機無法接手的執行個體	409, 503	HOST_UNREACHABLE, START_REFUSED, START_UNAVAILABLE	執行個體仍然是 stopped。稍後重試 —— START_UNAVAILABLE 可以很快重試。訊息說主機已不再持有工作負載的 START_REFUSED 不會成功：銷毀後重新部署。
同一個呼叫方的請求太多	429	RATE_LIMITED	等 Retry-After 標頭裡的秒數（回應內容裡也有 retry_after_s），再重試。
請求內容超過大小上限	413	PAYLOAD_TOO_LARGE	回應內容帶有 limit_bytes。送小一點：大多數端點 1 MiB，範本 4 MiB。
憑證不能附加的 ssh_key_id：不是你自己的，或 —— 用 team 金鑰時 —— 不是現任成員的	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 INSTANCE_LIMIT_REACHED	只有在銷毀了至少一個執行個體之後才行。
409 OFFER_NOT_PINNABLE	要，換一項報價 —— 同一項永遠不會成功。
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，而那正好是你本來就不會被重複收費的情況。