錯誤代碼

當某件事被拒絕時，理由會以一小段機器可讀的代碼送回來。主控台會把其中大多數變成一則快顯通知；API 則以 JSON 回傳。

{
  "detail": {
    "code": "OFFER_UNAVAILABLE",
    "message": "This offer is no longer available"
  }
}

少數幾個代碼會在 code 和 message 之外多帶欄位 — DISK_TOO_LARGE 會回傳 max_disk_gb，MACHINE_DISK_EXHAUSTED 會回傳 available_disk_gb，讓用戶端可以把滑桿夾在上限內重試，不必再跑一次來回。

這兩個值不能互換，夾錯了會無限迴圈。max_disk_gb 是機器的總硬碟容量；available_disk_gb 是扣掉同一台機器上其他租戶以及 50 GB 主機保留之後剩下的。所以一台機器可以通過 DISK_TOO_LARGE 卻仍然回 MACHINE_DISK_EXHAUSTED — 即使是空機也一樣，因為那份保留永遠不出售。拿到 available_disk_gb 時請照它來夾。

驗證與組織範圍

狀態	代碼	原因	該怎麼做
401	`TOKEN_INVALID`	沒有 `Authorization` 標頭、權杖格式錯誤、API 金鑰未知或已撤銷，或是把 API 金鑰送到帳號端點	送出有效的 bearer token。像 `/v1/me` 和 `/v1/ssh-keys` 這類帳號端點需要已登入的工作階段，不是 `shk_` 金鑰
401	`TOKEN_EXPIRED`	工作階段權杖已過了效期	重新登入。無人看管的指令碼請改用 API 金鑰
403	`NOT_A_MEMBER`	`X-Org-Id` 指向一個你不屬於的組織	拿掉這個標頭以使用你的個人組織，或請管理員發邀請給你
403	`ORG_MISMATCH`	`X-Org-Id` 與這把 API 金鑰建立時所在的組織不符	移除這個標頭，或改用屬於那個組織的金鑰
403	`ADMIN_REQUIRED`	以成員身分或用 API 金鑰去做僅限管理員的動作 — 結帳、邀請、成員管理、團隊 API 金鑰	找管理員，或從已登入的管理員工作階段重做一次
400	`INVALID_ORG_ID`	`X-Org-Id` 不是一個有效的 id	從 `GET /v1/orgs` 複製 `id`

部署

狀態	代碼	原因	該怎麼做
402	`INSUFFICIENT_BALANCE`	你在部署或啟動執行個體時，餘額不足以支付這個執行個體一小時的費用——GPU 加上硬碟。餘額大於零並不夠	儲值餘額。只有管理員能儲值
409	`OFFER_UNAVAILABLE`	在你打開這項報價到你按下部署之間，該形態的最後一則空閒被拿走了	回到市集挑另一項報價。卡片上的數字只是一個快照，真正決定的是部署本身
404	`OFFER_NOT_FOUND`	`GET /v1/offers/{id}` 收到的 id 不存在，或已從型錄中撤下。針對未知報價的部署則會回傳 `OFFER_UNAVAILABLE`	重新列出報價，並使用目前有效的 id
422	`DISK_TOO_LARGE`	要求的 `disk_gb` 超過機器實際有的總容量。回應中帶有 `max_disk_gb`	要求的容量不要超過 `max_disk_gb`，或改挑硬碟更大的機器
409	`MACHINE_IN_MAINTENANCE`	這台機器已排定下線，時間太近，無法在上面啟動執行個體。回應中帶有 `next_maintenance`	改挑別台機器，或等這段維護時段過去再來。更遠的時段不會擋下部署——它會顯示在報價上
409	`MACHINE_DISK_EXHAUSTED`	這台機器的硬碟已經許諾給其他租戶了。一台機器同時承載多位租戶，硬碟是按剩餘量而不是總量出售的——所以這個錯誤可能緊接在一個通過了 `DISK_TOO_LARGE` 的 `disk_gb` 之後。回應中帶有 `available_disk_gb` 和 `requested_disk_gb`	用不超過 `available_disk_gb` 的值重試，或改挑別台機器。`available_disk_gb` 可能是 `0`
422	`OFFER_NOT_VM_CAPABLE`	一個 `vm` 啟動模式的範本被指到了無法執行虛擬機器的機器上	把範本部署到具備 VM 能力的報價上，或改挑其他啟動模式的範本
404	`TEMPLATE_NOT_FOUND`	範本 id 不存在，或該範本已被刪除	使用範本庫裡的範本，或別人給你的 `hash_id`
404	`SSH_KEY_NOT_FOUND`	這個 `ssh_key_id` 不是你的金鑰之一	列出 `GET /v1/ssh-keys`，並使用你自己帳號裡的 id。金鑰屬於使用者，不屬於組織

執行個體動作

狀態	代碼	原因	該怎麼做
404	`INSTANCE_NOT_FOUND`	這個執行個體 id 在請求所指向的組織裡不存在	檢查 id，也檢查你人在正確的組織裡
409	`INVALID_STATE`	這個動作在執行個體目前的狀態下不合法 — 去停止一個已經在停止的東西、去銷毀一個還在建立中的東西	等執行個體到達 `running` 或 `stopped`，再重試。請參閱執行個體狀態

範本

狀態	代碼	原因	該怎麼做
403	`TEMPLATE_IMMUTABLE`	你試圖編輯或刪除由 Superheat 精選維護的系統範本	先複製一份，再編輯你的副本
409	`TEMPLATE_NAME_TAKEN`	你的組織裡已經有同名的範本，比對時不分大小寫	換一個名稱
404	`TEMPLATE_NOT_FOUND`	這個 id 或 `hash_id` 找不到你看得到的範本	確認分享連結完整而且是最新的 — 啟動配方一改，`hash_id` 就會跟著換
422	`INVALID_TAB`	範本清單上的 `tab` 查詢參數不是範本庫的分頁之一	使用支援的 tab 值

SSH 金鑰

狀態	代碼	原因	該怎麼做
422	`INVALID_SSH_KEY`	這個值不是一行 OpenSSH 公開金鑰、金鑰內容不是有效的 base64，或類型不受支援	把 `.pub` 檔案的內容整份貼上，一整行，開頭是金鑰類型。請參閱支援的金鑰類型
409	`DUPLICATE_SSH_KEY`	你已經加過一把指紋相同的金鑰	用你已經有的那把金鑰，或先把舊的那筆刪掉
404	`SSH_KEY_NOT_FOUND`	這個金鑰 id 不是你的	金鑰是以使用者為單位。別的成員的金鑰你永遠看不到

團隊與邀請

狀態	代碼	原因	該怎麼做
400	`PERSONAL_ORG`	你試圖把別人邀請進個人組織	先建立一個正式的組織，再從那裡發邀請
404	`INVITE_NOT_FOUND`	邀請權杖不對，或這份邀請已被撤回	請管理員給你一條新的連結
410	`INVITE_USED`	這份邀請已經被接受過了	索取一條新的邀請連結
410	`INVITE_EXPIRED`	這份邀請已過了效期	索取一條新的邀請連結
404	`MEMBER_NOT_FOUND`	這位使用者不是這個組織的成員	重新整理團隊頁面 — 他可能已經被移除了
400	`LAST_ADMIN`	移除那位成員，或把他降級，會讓組織一個管理員都不剩	先把另一位成員升為管理員

餘額

狀態	代碼	原因	該怎麼做
422	`INVALID_AMOUNT`	自訂儲值金額缺漏，或超出可接受的範圍	挑 $10、$25 或 $100 方案包，或介於 $5 到 $1,000 之間的自訂金額
403	`ADMIN_REQUIRED`	由成員或用 API 金鑰嘗試結帳	請組織的管理員儲值餘額

API 金鑰

狀態	代碼	原因	該怎麼做
404	`API_KEY_NOT_FOUND`	這個金鑰 id 在這個組織裡不存在	重新列出你的金鑰，並使用目前有效的 id
403	`ADMIN_REQUIRED`	一把 API 金鑰試圖建立或撤銷另一把 API 金鑰，或成員試圖管理團隊層級的金鑰	請從已登入的工作階段建立與撤銷金鑰

未通過驗證檢查的請求

如果請求的內容或查詢字串不符合結構定義，它在抵達上面任何一項檢查之前就會被拒絕。它會回傳 422，並在 detail 之下附上一份欄位錯誤清單，而不是一個 code：

{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["body", "disk_gb"],
      "msg": "Input should be less than or equal to 20000"
    }
  ]
}

loc 項目會指出出問題的欄位。值得記住的界線是 disk_gb 介於 10 到 20,000、label 最多 64 個字元，以及日誌端點上的 tail 介於 1 到 1,000。

驗證與組織範圍​

部署​

執行個體動作​

範本​

SSH 金鑰​

團隊與邀請​

餘額​

API 金鑰​

未通過驗證檢查的請求​

相關內容​