當某件事被拒絕時，理由會以一小段機器可讀的代碼送回來。主控台會把其中大多數變成一則快顯通知，並使用你的主控台語言；它還不認得的代碼則顯示 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 | 送小一點的請求內容。範本的說明與啟動腳本各有自己的上限，遠在這個範圍之內 |
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 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 不是這個憑證可以附加的金鑰：不是你自己的，或者——用 team API 金鑰時——不是現任成員的 | 用工作階段權杖列出 GET /v1/ssh-keys，並使用你自己帳號裡的 id。金鑰屬於使用者，不屬於組織 |
| 409 | INSTANCE_LIMIT_REACHED | 組織裡尚未銷毀的執行個體已達 25 個——stopped、error 與正在銷毀的也算在內。回應中帶有 limit | 銷毀不再需要的執行個體，包括處於 error 的。主控台的提示是「你已達到此組織的執行個體上限。請先銷毀一個。」 |
| 422 | TEMPLATE_COMING_SOON | 範本被標記為即將推出：映像檔尚未發布，例如 Superheat CN 上來自 NVIDIA NGC（nvcr.io）的範本 | 換一個範本。主控台裡這類範本無法選取，所以通常只有 API 呼叫會遇到 |
| 422 | TEMPLATE_CUDA_TOO_NEW | 範本鎖定了較舊的 CUDA 堆疊（cuda_max），而這台機器的 CUDA 版本較新 | 挑一台 CUDA 版本不超過範本上限的機器，或換一個範本 |
| 422 | TEMPLATE_ARCH_UNSUPPORTED | 範本宣告了 amd64/x86_64 以外的架構；Superheat 的機器都是 x86_64 | 改用 x86_64 映像檔的範本 |
| 422 | TEMPLATE_REQUIRES_OWNER | 範本屬於別的組織，並且從帶有憑證的私有登錄庫拉取，只有擁有它的組織能部署。主控台的提示是「此範本從私有登錄庫拉取映像檔，只有擁有它的組織能部署。」 | 把它複製到你的組織並填入你自己的登錄庫憑證（前提是你有權拉取那個映像檔），或請擁有者部署 |
| 409 | OFFER_NOT_PINNABLE | 報價所在的機器沒有在機群控制平面登記，部署無法固定到它上面。市集清單不會顯示這類報價，通常只有拿著舊的 offer_id 才會遇到。主控台的提示是「這台機器目前無法部署。請選擇其他機器。」 | 重新列出報價另挑一項 |
本節的每個代碼都在保留任何東西之前回傳，所以被拒絕的部署什麼都不會建立，也不會產生任何費用。
執行個體動作
| 狀態 | 代碼 | 原因 | 該怎麼做 |
|---|
| 404 | INSTANCE_NOT_FOUND | 這個執行個體 id 在請求所指向的組織裡不存在 | 檢查 id，也檢查你人在正確的組織裡 |
| 409 | INVALID_STATE | 這個動作在執行個體目前的狀態下不合法 — 去停止一個已經在停止的東西、去啟動一個正在執行的東西。銷毀在 destroyed 以外的任何狀態下都允許 | 等執行個體到達 running 或 stopped，再重試。執行個體的 allowed_actions 列出目前合法的操作。請參閱執行個體狀態 |
| 409 | HOST_UNREACHABLE | 你啟動一個已停止的執行個體，而它所在的機器目前沒有連線。執行個體仍然是 stopped | 稍後再啟動 |
| 409 | START_REFUSED | 主機拒絕恢復這個執行個體，或已不再持有它的工作負載 —— API 的訊息會說明是哪一種。執行個體仍然是 stopped | 如果主機已不再持有工作負載，銷毀執行個體並重新部署；否則稍後再試 |
| 503 | START_UNAVAILABLE | 暫時無法完成恢復。執行個體仍然是 stopped；如果恢復其實已經完成，它會自己進入 running | 稍後重試 |
| 409 | CAPACITY_UNAVAILABLE | 你啟動的執行個體在餘額用完時 GPU 被釋放了（被自動停止的，或者你之前自己停止的），而它在那台機器上原來用的 GPU 現在正被別人使用，或者已停止服務。執行個體仍然是 stopped，硬碟完好。主控台的提示是「此執行個體使用的 GPU 目前正被他人使用，無法啟動。執行個體仍處於已停止狀態，磁碟完好——請稍後再試。」 | 稍後再啟動：啟動成功之前拿不到硬碟上的資料。一直不成功的話，唯一的出路是銷毀執行個體（硬碟會一起刪除）後重新部署。請參閱 GPU 被釋放之後 |
執行個體為何失敗
這些不是對某個請求的拒絕，而是執行個體落入 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 | 機器上已不存在此執行個體的工作負載。請銷毀後重新部署。 |
dispatch_unavailable | 無法連線排程器來恢復此執行個體。執行個體仍處於已停止狀態——請稍後再試。 |
gateway_unavailable | 無法連線機器來恢復此執行個體。執行個體仍處於已停止狀態——請稍後再試。 |
gpus_unavailable | 此執行個體在其機器上使用的 GPU 目前正被他人使用。執行個體仍處於已停止狀態，磁碟完好——請稍後再啟動，或將其銷毀。 |
workload_gone 有兩種來源：啟動時機器已不再持有這個工作負載，或者執行個體停止期間它的容器在機器上不見了。後者的執行個體會轉到 error，不再計費，只能銷毀。
排程器針對機器上的工作負載記錄的代碼。主控台會先顯示說明，並在下方以 詳細資訊 顯示主機自己的 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 | amount_minor 既不是方案包金額，也不在 ¥20 到 ¥10,000 之間。回應中帶有以分計的 min_minor 與 max_minor（預設 2000 與 1000000） | 挑 ¥50、¥100 或 ¥500 方案包，或填寫 min_minor 到 max_minor 之間的金額 |
| 422 | PROVIDER_NOT_ENABLED | 本站沒有開通所要求的付款方式：儲值開放之前的任何訂單，或網域啟用 HTTPS 之前的 wechat | 從 GET /v1/billing/config 回傳的 providers 裡挑一種。清單為空時，暫時無法線上儲值 |
| 503 | PROVIDER_NOT_CONFIGURED | 這個付款方式已開通，但伺服器上的憑證不完整 | 這是伺服器的設定問題，不是你的請求有誤。稍後再試；持續出現請寫信到 finance@superheat.cloud |
| 429 | TOO_MANY_OPEN_ORDERS | 你已經持有五個未付款、未失效的 QR Code | 付掉其中一個，或等它們失效（15 分鐘）。在同一個組織裡用同樣的方式與金額再次發起（開立發票的訂單除外），只要原本的 QR Code 還剩兩分鐘以上，就會拿回原本那一個。這五個的上限按你本人計算，跨所有組織 |
| 422 | INVOICE_PROFILE_REQUIRED | 以 want_invoice: true 下單，但組織還沒有儲存發票資料 | 先用 PUT /v1/billing/invoice-profile 儲存發票資料，或在主控台開啟 開立發票 並填好表單 |
| 404 | ORDER_NOT_FOUND | 這個訂單 id 在請求所指向的組織裡不存在 | 檢查 id，也檢查你人在下單時的那個組織裡 |
| 403 | ADMIN_REQUIRED | 由成員或用 API 金鑰建立儲值訂單，或讀寫發票資料 | 請組織的管理員儲值餘額。請參閱 儲值餘額 |
| 422 | INVALID_TIME_ZONE | GET /v1/billing/spend-daily 收到的 tz 不是 API 認得的 IANA 時區名稱 | 傳 Asia/Shanghai 這樣的名稱，或不傳 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 個字元。
相關內容