若某項功能無法正常運作，最快速確認問題出在您這端還是我們這端的方法，就是用另一個工具送出相同的請求。

大約十件「API 故障」的回報中，有九件最終都是 base URL 設定錯誤、API 金鑰過期、模型名稱拼寫錯誤，或是使用了三個 SDK 版本以前的教學裡的請求格式。

快速自我測試

將以下 curl 指令複製到終端機，將 YOUR_KEY 替換成您在 Dashboard 取得的 API 金鑰後執行。若能取得正常的回應，表示您的 API 金鑰、網路連線以及我們的後端都運作正常——問題出在您的客戶端程式碼或環境設定。

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

快速自我測試: 手邊沒有終端機？將相同的模型與 prompt 貼到 Dashboard 的 Playground 即可——效果相同，無需任何設定。

逐步檢查清單

您的 API 金鑰是否有效？

開啟 Dashboard → API Keys，確認金鑰與您程式碼中使用的一致。常見陷阱是複製貼上時在 "sk-air-" 前綴前帶入了空白字元。

症狀：401 Unauthorized。

base URL 是否正確？

base URL 必須為 https://api.airforce/v1——不可用 http，且必須包含 /v1 後綴。早於 OpenAI v1 路徑的教學有時會省略它。

症狀：404 Not Found，或 curl 無回應。

模型名稱拼寫是否正確？

模型 ID 區分大小寫。請前往 Models 頁面或呼叫 GET /v1/models 確認確切的 ID。拼寫錯誤或已棄用的模型會回傳明確錯誤，而非「運作但結果有誤」。

症狀：400 unknown_model 或 404 model_not_found。

請求主體的格式是否正確？

Chat completions 使用 messages 陣列；圖片生成使用 prompt + n；音訊 TTS 使用 input + voice。若將 chat 格式的請求主體送到 /v1/images/generations 會回傳 400——在不同文件之間複製片段時很容易忽略這一點。

症狀：400，且回應主體中指出了有問題的欄位。

您是否已達速率限制或配額上限？

429 = 本分鐘請求次數過多；402 = 您的方案或餘額已耗盡。兩者都可在 Dashboard 上查看。免費層的請求有獨立的上限，與付費方案的上限分開計算，因此付費模型可能正常回應，而免費模型卻被速率限制。

症狀：429 Too Many Requests 或 402 Payment Required。

該模型目前是否正常運作？

請查看 Models 頁面——供應商中斷時會顯示「degraded」或「major outage」。若某個模型故障而其他模型正常，這是我們會繞過的供應商問題，不是客戶端錯誤。

症狀：特定模型回傳 5xx，而其他模型運作正常。

HTTP 狀態碼的含義

每個錯誤回應都附有標準的 HTTP 狀態碼。了解每個狀態碼的意義，可以省去一張工單的往返。


400	您這端	Bad Request — JSON 格式錯誤、缺少必填欄位或含有未知參數。請修正請求主體。
401	您這端	Unauthorized — 缺少或無效的 API 金鑰。請確認 Authorization 標頭包含 "Bearer " 前綴。
402	您這端	Payment Required — 方案額度已耗盡或 Pay-as-you-go 餘額為零。請訂閱或儲值。
403	您這端	Forbidden — 您的方案或金鑰權限不允許使用此模型或端點。
404	您這端	Not Found — 未知的端點或模型 ID。請確認 URL 路徑與模型名稱拼寫。
413	您這端	Payload Too Large — 輸入內容超過模型的上下文視窗限制。請縮短 prompt。
429	您這端	Too Many Requests — 已達速率限制（RPM、RPD 或每日 token 上限）。請降低請求頻率或升級方案。
500	我們這端	Internal Server Error — 我們這端的 bug。若問題持續超過一分鐘，請回報。
502	我們這端	Bad Gateway — 後端正在重新啟動（我們每天部署數次）。請等待 5–10 秒後重試。
503	我們這端	Service Unavailable — 該模型的所有上游供應商同時發生故障。若持續超過幾分鐘，請回報。

💡

判斷準則: 4xx 代碼表示您的客戶端做了伺服器拒絕的操作；5xx 代碼表示我們未能處理一個有效的請求。回應中的 JSON 錯誤主體通常會指出觸發檢查的欄位名稱。

真的是 Bug 的情況

若上方 curl 自我測試成功，但完全相同的請求從您的程式碼發出卻失敗，問題出在您的客戶端（或其所使用的函式庫）。若自我測試本身回傳 5xx，或回傳的 4xx 訊息與您的請求內容不相符，那就值得回報。

如何有效回報問題

請從 Dashboard 開立支援工單，或在 Discord 的 #support 頻道發文。請附上：

完整的 HTTP 狀態碼與回應主體（如有 cf-ray 回應標頭，請一併提供）。
大約的 UTC 時間戳記。
模型名稱及您所呼叫的端點。
可重現問題的最精簡 cURL（請遮蔽您的真實 API 金鑰！）。
上方的自我測試在相同金鑰下是否對您有效。

ℹ️

如何有效回報問題: 附有這些資訊的工單通常第一次就能得到實質解答；缺乏資訊的工單幾乎都需要來回確認才能協助處理。

在 Discord 的 #support 頻道發問

回報 Bug 前請先確認