錯誤排查總覽

本區塊收錄瓜瓜AI API 最常見的錯誤與排查方式。先看下方狀態碼對照，再進入對應頁面。

狀態碼對照

狀態碼	分類	意義	文件
400	用戶端錯誤	請求格式或參數有問題	400 Bad Request
401	用戶端錯誤	未通過驗證（金鑰問題）	401 Unauthorized
403	用戶端錯誤	已驗證但無權限	403 Forbidden
404	用戶端錯誤	路徑或資源不存在（多半是 Base URL 寫錯）	見 Base URL
429	用戶端錯誤	請求過於頻繁，超過速率限制	429 Too Many Requests
5xx	伺服器錯誤	上游服務異常	5xx 上游錯誤

先分辨「誰的問題」

• 4xx：請求本身有問題，重試通常沒用，要先修正請求。
• 5xx：服務端問題，適合間隔後重試。
• 完全沒有狀態碼：網路、DNS、Proxy 或 TLS 問題，與金鑰無關。

通用排查流程

1. 記下完整錯誤資訊：狀態碼、回應主體、發生時間、使用的模型。

2. 用 curl 重現：排除客戶端或框架的影響。

   curl -i https://api.guagua5487.xyz/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $GUAGUA_API_KEY" \
     -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}]}'

3. 確認 Base URL：必須是 https://api.guagua5487.xyz/v1，不多不少，見 Base URL。

4. 確認金鑰：只填金鑰本身，不要包含 Bearer 或引號。

5. 確認模型代號：見 支援模型。

6. 確認請求主體是合法 JSON：常見於手寫 JSON 時多出逗號或缺少引號。

7. 仍然失敗：帶著上述資訊回報，並附上回應中的 id（若有）。

快速檢查清單

• [ ] 網址為 https://api.guagua5487.xyz/v1/chat/completions
• [ ] 使用 POST 方法
• [ ] 帶有 Authorization: Bearer <API_KEY>
• [ ] 帶有 Content-Type: application/json
• [ ] 請求主體是合法 JSON
• [ ] model 是實際存在的代號
• [ ] messages 是非空陣列，每筆都有 role 與 content
• [ ] 若使用串流，客戶端與代理都支援 SSE

常見症狀速查

症狀	最可能的原因	先看
401 一直出現	金鑰錯誤、多了空白或 Bearer	401
404	Base URL 少了 /v1 或路徑重複	Base URL
400 提到 model	模型代號錯誤	支援模型
400 提到 messages	訊息結構錯誤	Chat Completions
429 突然出現	併發或頻率過高	429
502 / 503	上游暫時異常	5xx
串流中斷	網路或逾時	串流輸出
請求逾時無回應	網路、Proxy、防火牆	Base URL

待補充

瓜瓜AI 的實際錯誤回應主體格式、自訂錯誤碼與速率限制數值尚待官方確認。本區塊僅就標準 HTTP 語意與通用排查方式說明，不會編造特定錯誤碼或限制數字。

相關頁面

• 快速開始
• Base URL
• Chat Completions
• 串流輸出