故障排除

    認證類錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    invalid api key401API Key 無效、已過期、已撤銷或已停用請進入控制台 → API Keys 頁面，確認 Key 狀態為"啟用"，如已過期請重新產生

    路由與模型錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    no model config found for: {model}404請求的模型 ID 不存在進入模型列表，確認模型 ID 拼寫正確
    model field is required400請求體中缺少 model 欄位在請求 JSON 中新增 "model": "模型名稱"
    invalid or empty requested model400請求的模型名稱為空或非法進入模型列表，確認使用正確的模型 ID 格式
    unknown api path404API 路徑錯誤請確認 Base URL 為 https://api.gate.ai/openai/v1 或 https://api.gate.ai/anthropic

    請求參數錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    invalid JSON body400請求體 JSON 格式不合法檢查請求體是否為合法的 JSON 格式
    failed to read request body400請求體讀取失敗確認請求體未損壞，Content-Type 設定為 application/json
    failed to rewrite request body500請求體重寫失敗（閘道內部）請重試，若持續出現，請聯絡技術支援
    images are not supported by this model400目標模型不支援圖片輸入更換支援多模態（圖片）的模型，如 gpt-4o
    audio is not supported by this model400目標模型不支援音訊輸入更換支援音訊輸入的模型
    unsupported parameter: max_tokens400部分模型不支援 max_tokens 參數改用 max_completion_tokens 參數

    配額與限流錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    api key budget quota exceeded429API Key 預算額度已用盡進入控制台 → API Keys → 預算設定，提高預算上限或等待配額重置
    guardrail budget limit exceeded429護欄預算限制已超出檢查護欄配置中的預算限制，調高限額或降低使用頻率
    organization guardrail budget limit exceeded429組織級護欄預算已超出聯絡組織管理員調整組織級預算限制
    model not allowed by guardrail policy403模型不在護欄策略允許範圍內進入控制台 → 護欄設定，將目標模型新增到允許清單
    The free model usage has reached its daily global limit today.429免費模型全域日限額已達上限等待次日重置，或升級到付費方案使用無限制模型
    The free model usage has reached its daily limit today.429個人免費模型日限額已達上限等待次日重置，或升級到付費方案
    Guest daily spending limit exceeded. Please try again tomorrow or upgrade to a paid plan.429訪客身分日累計限額已超出註冊帳號並升級到付費方案，或等待次日重置

    計費與餘額錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    Pending payment {amount} USD — Please top up...402帳戶餘額不足且存在欠費前往 Gate Pay 完成儲值
    Insufficient balance and account in debt402餘額不足且帳戶處於欠費狀態前往 Gate Pay 完成儲值
    billing model info not found for model "{model}"400模型的計費資訊不存在確認模型 ID 正確，若為新模型，請聯絡技術支援配置計費規則
    billing model info is ambiguous for model "{model}"400模型計費資訊存在歧義（多筆匹配）請聯絡技術支援排查模型計費配置
    billing configuration error500計費規則配置錯誤（服務端）請聯絡技術支援修復計費配置

    上游服務錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    bad gateway502閘道與上游服務通訊失敗請重試，若持續出現，請檢查服務狀態頁或聯絡技術支援
    upstream service unavailable502上游 AI Provider 不可用稍後重試，或切換到其他可用模型
    upstream service error502上游 AI Provider 返回錯誤檢查請求參數是否符合目標模型要求；若持續出現請聯絡技術支援
    request timeout504請求上游逾時減少輸入長度或增加逾時時間後重試
    no provider handler configured for protocol502閘道未配置對應的協議處理器請聯絡技術支援檢查閘道配置

    服務端內部錯誤

    錯誤資訊HTTP 狀態碼原因解決方案
    internal server error500閘道內部錯誤請重試，若持續出現，請攜帶 Request ID 聯絡技術支援
    failed to record request log500請求日誌記錄失敗不影響請求結果，可忽略；若頻繁出現請聯絡技術支援
    failed to list models500模型列表查詢失敗請重試，若持續出現，請聯絡技術支援

    常見場景速查

    Base URL 錯誤

    bash
    1# ❌ 錯誤2https://api.gate.ai/v1/chat/completions34# ✅ 正確5https://api.gate.ai/openai/v1/chat/completions  # openai 協議6https://api.gate.ai/anthropic/v1/messages  # anthropic 協議

    max_tokens 參數不相容

    javascript
    1// ❌ 部分模型不支援2{ "model": "gpt-4o", "max_tokens": 100 }34// ✅ 使用 max_completion_tokens5{ "model": "openai/gpt-5.5", "max_completion_tokens": 100 }

    API Key 格式

    bash
    1# ✅ 正確的請求標頭2Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx # openai 協議3X-api-key: sk-xxxxxxxxxxxxxxxxxxxx # anthropic 協議