外觀
401 Unauthorized
401 Unauthorized 代表伺服器沒有收到有效的驗證資訊。最常見的原因是 API Key 缺失、格式錯誤或已失效。
標準語意
這是通用的 HTTP 狀態碼，意義為「請求未通過身分驗證」。請注意：連線本身是正常的，問題出在金鑰。
常見原因
| 原因 | 說明 | 修正 |
|---|---|---|
| 完全沒帶金鑰 | 缺少 Authorization 標頭 | 補上標頭 |
| 標頭格式錯誤 | 忘了 Bearer 前綴，或寫成 Basic | 使用 Authorization: Bearer <API_KEY> |
| 金鑰含多餘字元 | 貼上時帶了空白、換行、引號 | 重新複製，只留金鑰本身 |
| 金鑰重複加前綴 | 環境變數已含 Bearer ，程式又加一次 | 檢查兩處 |
| 金鑰無效或已刪除 | 金鑰被停用、刪除或複製不完整 | 重新取得金鑰 |
| 環境變數未生效 | 變數名拼錯、未載入 .env、容器未傳入 | 印出長度檢查（不要印出內容） |
| 用了錯的環境 | 把測試金鑰用到正式環境（或反之） | 確認金鑰對應的環境 |
| 金鑰被自動遮蔽 | 某些平台會把日誌中的金鑰改寫 | 確認實際送出的標頭 |
待補充
瓜瓜AI 的 API Key 格式（前綴、長度）、有效期限與管理方式尚待官方確認。若錯誤主體有明確說明，請以該訊息為準。
排查步驟
1. 檢查實際送出的標頭
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"}]}'-i 會顯示回應標頭與狀態碼。若金鑰為空，標頭會變成 Authorization: Bearer ，這同樣會回 401。
2. 確認金鑰有被正確載入（不要印出內容）
bash
# 只印長度，避免金鑰外洩到日誌
echo "key length: ${#GUAGUA_API_KEY}"powershell
"key length: $($env:GUAGUA_API_KEY.Length)"python
import os
key = os.environ.get("GUAGUA_API_KEY", "")
print("key present:", bool(key), "length:", len(key))若長度為 0，代表環境變數沒有設定成功。
3. 確認程式碼沒有重複加前綴
python
# ✗ 環境變數已含 "Bearer " 時會變成 "Bearer Bearer sk-..."
headers = {"Authorization": f"Bearer {os.environ['GUAGUA_API_KEY']}"}
# ✓ 環境變數只放金鑰本身
headers = {"Authorization": f"Bearer {os.environ['GUAGUA_API_KEY']}"}
# 且 .env 內容為：GUAGUA_API_KEY=YOUR_API_KEYSDK 會自動處理
使用 OpenAI SDK 時，只需把金鑰交給 api_key，不要自己加 Bearer ：
python
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.guagua5487.xyz/v1")4. 確認沒有把金鑰貼錯位置
| 錯誤做法 | 問題 |
|---|---|
| 金鑰填在 Base URL 欄位 | 路徑錯誤，通常回 404 或 401 |
| 金鑰填在模型欄位 | 模型不存在 |
| 金鑰前後有空白 | 被視為不同字串 |
| 金鑰放在 URL 查詢參數 | 瓜瓜AI 未確認支援此方式 |
安全提醒
| 情境 | 建議 |
|---|---|
| 金鑰疑似外洩 | 立即更換，並檢查用量 |
| 需要貼程式碼求助 | 一律以 YOUR_API_KEY 取代真實金鑰 |
| 前端程式碼 | 不要放金鑰，改由後端代理 |
| 版本控制 | 將 .env 加入 .gitignore |
| 日誌 | 不要記錄完整的 Authorization 標頭 |
| 多環境 | 開發／測試／正式使用不同金鑰 |
bash
# .gitignore
.env
.env.*與 403 的差別
| 狀態碼 | 意義 | 下一步 |
|---|---|---|
401 | 沒有有效的身分（金鑰問題） | 修正金鑰 |
403 | 身分有效，但沒有該資源的權限 | 見 403 Forbidden |