外觀
403 Forbidden
403 Forbidden 代表伺服器知道你是誰，但拒絕讓你存取該資源。與 401 不同，問題不是「身分無法辨識」，而是「權限不足」。
標準語意
這是通用的 HTTP 狀態碼，意義為「已驗證但無權存取」。重複送出同樣的請求不會成功，需要調整權限或改用有權限的資源。
與 401 的差別
| 狀態碼 | 意義 | 代表 | 處理方向 |
|---|---|---|---|
401 | 未通過驗證 | 金鑰缺失、格式錯誤、無效 | 修正金鑰，見 401 Unauthorized |
403 | 已驗證但無權限 | 金鑰有效，但沒有該操作的權限 | 調整權限、模型或方案 |
常見原因
| 原因 | 說明 | 處理 |
|---|---|---|
| 金鑰無該模型權限 | 金鑰只被授權使用部分模型 | 改用有權限的模型，或申請權限 |
| 方案／額度限制 | 目前方案不含該功能，或額度已用盡 | 確認方案內容（待補充） |
| 金鑰被停用或凍結 | 因違規、欠費或安全事件被停用 | 聯繫官方確認 |
| 功能未開放 | 該端點或參數尚未對你的帳號開放 | 改用已開放的介面 |
| 存取被政策阻擋 | 內容或用途違反服務政策 | 調整使用方式 |
| 來源限制 | 金鑰綁定特定來源（IP／網域）而請求不符 | 確認來源設定（待補充） |
| 走錯環境 | 用測試金鑰存取正式資源（或反之） | 使用對應環境的金鑰 |
待補充
瓜瓜AI 的權限模型（是否區分模型權限、來源限制、方案層級）、以及 403 的錯誤訊息格式尚待官方確認。本頁僅就標準 HTTP 語意與通用原因說明。
排查步驟
1. 確認金鑰本身有效
先用最小請求測試，並區分 401 與 403：
bash
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"}]}'| 結果 | 判讀 |
|---|---|
401 | 金鑰問題 → 見 401 |
403 | 金鑰有效但無權限 → 繼續下方步驟 |
200 | 金鑰與模型皆正常，原本的問題可能來自其他參數 |
2. 讀取回應主體
403 的回應主體通常會說明原因（例如權限不足、方案限制）。請完整保留內容作為排查與回報依據。
不要只看狀態碼
不同服務對「模型不存在」「無權使用該模型」的實作不同，可能是 403 也可能是 400／404。回應主體比狀態碼更能指出真正原因。
3. 換一個模型測試
若換成其他已知可用的模型就成功，代表是該模型的權限問題，而非金鑰整體失效。詳見 支援模型。
4. 確認環境與方案
| 檢查點 | 說明 |
|---|---|
| 金鑰環境 | 測試金鑰不應打到正式資源 |
| 方案內容 | 確認方案是否包含該模型或功能（待補充） |
| 額度狀態 | 確認是否已用盡或到期（待補充） |
| 近期變更 | 是否剛調整過方案或金鑰權限 |
5. 排除網路中介
少數情況下，公司 Proxy、WAF 或 CDN 會自行回傳 403。判斷方式：
- 回應主體是否為瓜瓜AI 的格式，而非 HTML 錯誤頁。
- 換網路環境（例如手機熱點）是否仍失敗。
- 是否連其他 HTTPS 網站也異常。
什麼時候該聯繫官方
若以下條件都成立，建議聯繫官方並附上資訊：
- 金鑰在最小請求下仍回 403；
- 換多個模型皆相同；
- 回應主體明確指出權限或方案問題；
- 你預期該權限應該存在。
回報時請提供：發生時間、使用的模型、狀態碼、完整回應主體、請求 ID（若有）。請勿提供完整金鑰。