當某件事被拒絕時，理由會以一小段機器可讀的代碼送回來。主控台會把其中大多數變成一則以你主控台語言顯示的快顯通知；主控台還不認得的代碼，則會顯示 API 自己的訊息，那是英文。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 |
| 403 | MFA_REQUIRED | 你的帳號已登錄兩步驗證，而這個工作階段權杖尚未完成第二步 | 重新登入，並輸入驗證器應用程式中的驗證碼。主控台會自動把你帶到那一步。API 金鑰不受影響 |
| 503 | AUTH_UNAVAILABLE | API 目前無法檢查你的登入——讀不到簽章金鑰或兩步驗證狀態 | 稍後重試。你的工作階段仍然有效 |
每個請求都有的限制
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 429 | RATE_LIMITED | 同一個呼叫端的請求太多——已登入的使用者、一把 API 金鑰，或是匿名請求的 IP 位址。每個 /v1 請求都計入每分鐘 600 次；POST、PUT、PATCH 與 DELETE 另外也計入每分鐘 60 次。某個 IP 位址的請求若每分鐘超過 60 次因未通過驗證而被拒，從它送出的每個尚未成功過的憑證也會收到這個代碼 | 等待 Retry-After 標頭中的秒數（回應主體裡也有 retry_after_s），再重試。/v1/health 永遠不受限制 |
| 413 | PAYLOAD_TOO_LARGE | 請求主體超過端點接受的大小：大多數端點為 1 MiB，/v1/templates 之下為 4 MiB。回應中帶有 limit_bytes | 送出較小的主體。範本的 readme 與啟動腳本各有自己的上限，遠在這之內 |
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 402 | INSUFFICIENT_BALANCE | 你在部署或啟動執行個體時，餘額不足以支付組織在這個執行個體執行時一小時的消耗——它的 GPU 與硬碟，加上執行中、啟動中或建立中執行個體的 GPU 與硬碟，以及已停止執行個體的硬碟。餘額大於零並不夠。回應中帶有 balance_micro 與 required_micro | 儲值餘額。只有管理員能儲值 |
| 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。金鑰屬於使用者，不屬於組織 |
| 402 | PAYMENTS_FROZEN | 這個組織有一筆付款爭議尚未結案。在它結案之前，部署與啟動已停止的執行個體都會暫停，其間已停止執行個體的 GPU 也會在機器支援的情況下被釋放 | 等爭議結案。請見交易與花費與付款爭議未結期間 |
| 409 | INSTANCE_LIMIT_REACHED | 這個組織已經有 25 個尚未銷毀的執行個體。計入上限的不只是執行中的執行個體，已停止與處於 error 的也算。回應中帶有 limit | 銷毀不再需要的執行個體——停止並不會空出名額——然後再部署 |
| 422 | TEMPLATE_COMING_SOON | 這個範本的映像檔還沒有發布，因此無法啟動 | 換一個範本。主控台會把這類範本顯示為尚未開放 |
| 422 | TEMPLATE_CUDA_TOO_NEW | 範本鎖定了較舊的 CUDA 堆疊（也就是它的 cuda_max），而這台機器回報的 CUDA 版本較新。容器跑得起來，但裡面的框架沒有適用於這張 GPU 的核心 | 挑一台 CUDA 版本不高於範本上限的機器，或挑一個為較新 GPU 建置的範本 |
| 422 | TEMPLATE_ARCH_UNSUPPORTED | 範本宣告的架構不是 x86_64。Superheat 的每一台主機都是 x86_64 | 使用 amd64 映像檔 |
| 409 | OFFER_NOT_PINNABLE | 這項報價背後的機器沒有在控制平面註冊，部署無法固定到它上面。這類報價不會出現在市集裡，所以這通常代表你用的是過時的報價 id | 重新列出報價，改挑另一項 |
| 422 | TEMPLATE_REQUIRES_OWNER | 這個範本從私有登錄庫拉取，只有擁有它的組織才能部署——它的登錄庫密碼絕不會代替別人使用 | 複製這個範本，在副本上填入你自己的登錄庫憑證，然後部署副本 |
上表中的每個錯誤代碼，都在任何東西被保留下來之前就回傳，所以被拒絕時什麼都不會建立，也不會收費。
執行個體動作
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 404 | INSTANCE_NOT_FOUND | 這個執行個體 id 在請求所指向的組織裡不存在 | 檢查 id，也檢查你人在正確的組織裡 |
| 409 | INVALID_STATE | 這個動作在執行個體目前的狀態下不合法 — 去停止一個已經在停止的東西、去啟動一個正在執行的東西。除了 destroyed 以外，每個狀態都可以銷毀 | 等執行個體到達 running 或 stopped，再重試。執行個體的 allowed_actions 會列出此刻合法的動作。請參閱執行個體狀態 |
| 409 | HOST_UNREACHABLE | 你啟動了一個已停止的執行個體，而它所在的機器目前沒有連線。執行個體仍是 stopped | 稍後再啟動一次 |
| 409 | START_REFUSED | 主機拒絕恢復這個執行個體，或已不再持有它的工作負載——訊息會說明是哪一種。執行個體仍是 stopped | 若主機已不再持有工作負載，請銷毀執行個體並重新部署；否則稍後再試 |
| 409 | CAPACITY_UNAVAILABLE | 你啟動的執行個體的 GPU 已被釋放——餘額到了零，或一筆付款爭議凍結了付款——而另一位租用者現在正在使用其中一張。啟動必須在同一台機器上取回同樣的 GPU。執行個體仍是 stopped，硬碟還在 | 稍後再試。如果等不及，就先把資料複製出來再銷毀它。請見停止與銷毀 |
| 503 | START_UNAVAILABLE | 目前無法完成恢復。執行個體仍是 stopped；如果恢復最後還是落地了，它會自己進入 running | 稍候再試 |
執行個體為何失敗
這些不是對某個請求的拒絕，而是執行個體落入 error，或是某次停止或啟動沒有落地、執行個體回到 running 或 stopped 時帶著的 error_code。執行個體頁面會用你的主控台語言說明原因——出錯的執行個體顯示在 發生了什麼問題 下，執行中或已停止的執行個體顯示在 上一個操作沒有完成 下——代碼本身寫在下方，方便你轉告支援人員。在其他狀態下，頁面會隱藏這兩個欄位，因為它們描述的是更早的狀態。透過 API，它們就是執行個體上的 error_code 與 error_message。
平台自己設定的代碼。主控台的說明會取代 API 回傳的英文 error_message：
error_code | 主控台顯示的內容 |
|---|
provision_failed | 排程器沒有接受這次部署。未產生任何費用——請銷毀後重試。 |
provision_lost | 部署從未送達排程器。未產生任何費用——請銷毀後重試。 |
provision_timed_out | 工作負載始終沒有被放置到機器上。請銷毀後重試。 |
dispatch_job_missing | 排程器中已不存在此執行個體的工作負載。請銷毀後重新部署。 |
stop_timed_out | 機器沒有確認停止。執行個體仍在執行並計費，系統正在重試停止。 |
start_timed_out | 機器沒有確認恢復。執行個體仍處於已停止狀態——請再次嘗試啟動。 |
workload_completed | 工作負載已自行結束，其 GPU 已釋放——請銷毀此執行個體。 |
machine_unreachable | 啟動時此執行個體所在的機器未連線。執行個體仍處於已停止狀態——請稍後再試。 |
start_refused | 機器拒絕恢復此執行個體。執行個體仍處於已停止狀態。 |
workload_gone | 機器上已不存在此執行個體的工作負載。請銷毀後重新部署。 |
gpus_unavailable | 此執行個體在其機器上使用的 GPU 目前正被他人使用。執行個體仍處於已停止狀態，磁碟完好——請稍後再啟動，或將其銷毀。 |
dispatch_unavailable | 無法連線排程器來恢復此執行個體。執行個體仍處於已停止狀態——請稍後再試。 |
gateway_unavailable | 無法連線機器來恢復此執行個體。執行個體仍處於已停止狀態——請稍後再試。 |
排程器針對機器上的工作負載記錄的代碼。主控台會先顯示說明，並在下方以 詳細資訊 顯示主機自己的 error_message，那往往就是確切原因——一個結束狀態、一個缺少的映像檔：
error_code | 主控台顯示的內容 |
|---|
workload_failed | 容器在機器上執行失敗。 |
workload_lost | 機器失去了對容器的追蹤。 |
workload_exit_nonzero | 容器因錯誤而結束。 |
workload_terminal | 工作負載在機器上已經結束。 |
start_timeout | 容器沒有在規定時間內啟動。很大的映像檔下載時間可能超出允許範圍。 |
deadline_exceeded | 工作負載達到了時間上限。 |
machine_lost | 機器已離線。 |
machine_gone | 機器已離開機群。 |
unknown_to_gateway | 機器上沒有此工作負載的記錄。 |
placement_error | 無法將工作負載放置到機器上。 |
drain | 機器因維護已停止服務。 |
manual_reschedule | 支援人員已將此工作負載移至另一台機器。 |
image_not_provisioning_capable | 此映像檔無法以該範本的啟動模式啟動。 |
launch_mode_unsupported | 沒有機器支援該範本的啟動模式。 |
vm_not_supported | 這台機器無法執行虛擬機器。 |
兩張表都沒有的代碼仍會原樣顯示，並附上 API 送來的訊息。接下來該怎麼做，請見疑難排解。
瀏覽報價
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 422 | INVALID_CURSOR | GET /v1/offers 的 cursor 不是 API 發出的，或是為另一種 sort 發出的 | 以同一個 sort 原樣傳回上一頁的 next_cursor，或省略它從頭開始。請參閱報價 |
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 403 | TEMPLATE_IMMUTABLE | 你試圖編輯或刪除由 Superheat 精選維護的系統範本 | 先複製一份，再編輯你的副本 |
| 409 | TEMPLATE_NAME_TAKEN | 你的組織裡已經有同名的範本，比對時不分大小寫 | 換一個名稱 |
| 404 | TEMPLATE_NOT_FOUND | 這個 id 或 hash_id 找不到你看得到的範本 | 確認分享連結完整而且是最新的 — 啟動配方一改，hash_id 就會跟著換 |
| 422 | INVALID_TAB | 範本清單上的 tab 查詢參數不是範本庫的分頁之一 | 使用支援的 tab 值 |
| 422 | INVALID_CURSOR | 範本清單上的 cursor 不是 API 發出的 | 把上一頁的 next_cursor 原封不動傳回去，或省略它從頭開始 |
| 409 | PUBLIC_TEMPLATE_LIMIT_REACHED | 你的組織已經有 50 個公開範本。回應中帶有 limit | 先把其中一個改為私人或刪除一個，再公開新的 |
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_REVOKED | 發出邀請的人已不再是該組織的管理員，所以邀請已失效 | 向目前的管理員索取新的邀請 |
| 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 金鑰嘗試結帳 | 請組織的管理員儲值餘額 |
| 422 | INVALID_TIME_ZONE | GET /v1/billing/spend-daily 收到的 tz 不是 API 認得的 IANA 時區名稱 | 送出例如 Europe/Berlin 的名稱，或省略 tz 以使用 UTC |
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。範本與部署方面：最多 100 個環境變數項目（範本上與 env_overrides 中皆是），每個值最多 4,096 個字元；最多 32 個連接埠；最多 32 個限制條件選擇器；cuda_min、cuda_max 與 arch 最多 32 個字元；範本與報價清單的 limit 介於 1 到 200；報價清單的 q 最多 100 個字元。
相關內容