常見問題與錯誤處理

按照 Base URL、API Key、模型、餘額和客戶端順序處理常見問題。

遇到問題時，不要先反覆重試。先按「地址 → API Key → 模型 → 餘額/方案 → 客戶端 → 網路」的順序檢查，這樣最容易判斷問題是在本機設定、帳戶狀態，還是服務端。

現象	先檢查什麼	下一步
401	API Key 是否完整、是否被撤銷、認證標頭是否正確	重新複製金鑰並查看 API Key 管理
403	餘額、方案、訂閱、金鑰期限和分組	查看儀表板與餘額和可用渠道
400	Base URL、請求格式和模型 ID	回到對應的 API 或客戶端教學
429	請求頻率、並行數、配額和 `Retry-After`	降低負載後等待，不要輪換金鑰
502/503	上游帳戶、模型狀態或暫時容量	保留 request ID，有限次數重試或聯絡支援
沒有任何用量記錄	Base URL、代理、DNS 和客戶端是否真的發出了請求	先用最小 `curl` 請求測試

前置條件

一把已知有效的 API Key；不要使用控制台登入密碼或 Cookie 代替。
從可用渠道複製的完整模型 ID。
失敗時間、時區、客戶端名稱與版本、完整端點和 HTTP 狀態。
分享截圖或日誌前，移除 API Key、Cookie、完整提示內容和個人資料。

操作步驟

先用最小請求確認服務

先不要使用長提示、圖片、工具呼叫或高並行。用最簡單的請求判斷帳戶和端點是否可用。

Bash 或 Zsh：

export AIXHUB_API_KEY="sk-your-key"
export AIXHUB_MODEL="panel-model-id"

curl -i https://api.aixhub.org/v1/messages \
  -H "x-api-key: $AIXHUB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  --data "{\"model\":\"$AIXHUB_MODEL\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Reply OK\"}]}"

Windows PowerShell：

$env:AIXHUB_API_KEY = "sk-your-key"
$env:AIXHUB_MODEL = "panel-model-id"

$headers = @{
  "x-api-key" = $env:AIXHUB_API_KEY
  "anthropic-version" = "2023-06-01"
}
$body = @{ model = $env:AIXHUB_MODEL; max_tokens = 16; messages = @(@{ role = "user"; content = "Reply OK" }) } | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "https://api.aixhub.org/v1/messages" -Method Post -Headers $headers -ContentType "application/json" -Body $body

讀取回應並對照控制台

先記錄 HTTP 狀態和回應中的錯誤代碼或 message。
再查看「可用渠道」，確認模型 ID、協定和分組仍然可用。
到用量記錄按時間查找這次測試，確認請求是否到達服務以及是否產生費用。
最小請求成功後，一次只恢復一項內容，例如長提示、串流、圖片或工具呼叫。

查詢錯誤代碼

如果已取得 HTTP 狀態、錯誤代碼或串流失敗事件，請直接前往錯誤代碼查詢來源、含義、處理方式與重試邊界。完整表格只在該頁維護，避免兩份說明產生差異。

驗證結果

最小請求成功，回應中的模型、時間和狀態可以在用量記錄中對應；客戶端恢復後也不再重複使用錯誤設定。

常見問題

提交支援資訊

請提供：發生時間與時區、客戶端名稱與版本、端點、模型 ID、HTTP 狀態、request ID、已遮蔽的回應內容，以及用量記錄是否出現。

不要提供完整 API Key、Cookie、控制台登入 Token、完整提示內容或未遮蔽的使用者資料。

下一步

已取得狀態或代碼時前往錯誤代碼；仍無法重現時回到認證與 Base URL，再查看API Key 管理或可用渠道。