外觀
400 Bad Request
400 Bad Request 代表伺服器無法理解或處理你的請求。連線與驗證通常沒問題，問題出在請求內容本身。
標準語意
這是通用的 HTTP 狀態碼，意義為「用戶端請求有誤」。由於重試同樣的請求不會成功，請先修正請求內容。
常見原因
| 原因 | 說明 | 檢查方式 |
|---|---|---|
| JSON 格式錯誤 | 多餘逗號、缺少引號、括號不匹配、用了單引號 | 用 JSON 驗證工具檢查 |
| 缺少必填欄位 | 沒有 model 或 messages | 對照 Chat Completions |
messages 結構錯誤 | 不是陣列、缺少 role 或 content | 檢查每筆訊息 |
| 模型代號不存在 | 拼錯、大小寫不符、模型已下線 | 見 支援模型 |
| 參數型別錯誤 | 該填數字卻填字串（例如 "max_tokens": "100"） | 對照參數表 |
| 參數超出範圍 | 例如負數或超出上限 | 移除或調整該參數 |
| 內容過長 | 超過上下文或長度上限 | 縮短輸入（實際上限待補充） |
| 未支援的參數 | 送出了該模型不支援的欄位 | 逐一移除測試 |
| 標頭問題 | 缺少 Content-Type: application/json | 檢查請求標頭 |
待補充
瓜瓜AI 實際的長度上限、參數範圍與錯誤訊息文字尚待官方確認。若錯誤主體中有明確欄位名稱，請以該訊息為主要線索。
排查步驟
1. 確認請求主體是合法 JSON
bash
# 把請求主體存成檔案，先驗證 JSON
echo '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}]}' > body.json
python -m json.tool body.json常見錯誤：
jsonc
// ✗ 多餘逗號
{ "model": "MODEL_ID", "messages": [], }
// ✗ 單引號不是合法 JSON
{ 'model': 'MODEL_ID' }
// ✓ 正確
{ "model": "MODEL_ID", "messages": [{ "role": "user", "content": "ping" }] }2. 用最小請求測試
先只留必填欄位，能成功再逐一加回其他參數：
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"}]}'3. 確認 messages 結構
json
{
"model": "MODEL_ID",
"messages": [
{ "role": "system", "content": "你是一位助理。" },
{ "role": "user", "content": "你好" }
]
}| 檢查點 | 正確 | 錯誤 |
|---|---|---|
| 型別 | 陣列 [] | 物件 {} 或字串 |
| 每筆欄位 | 有 role 與 content | 缺少其一 |
content 型別 | 字串 | 數字、null、巢狀物件 |
role 值 | system / user / assistant（tool 支援狀態待補充） | 自創角色名稱 |
| 空陣列 | 至少一筆訊息 | "messages": [] |
4. 確認模型代號
bash
# 若模型列表端點可用（待確認）
curl https://api.guagua5487.xyz/v1/models \
-H "Authorization: Bearer $GUAGUA_API_KEY"代號請直接複製，不要自行猜測。詳見 支援模型。
5. 檢查程式碼中的序列化
python
# ✗ 手動組字串容易出錯
body = '{"model":"MODEL_ID","messages":[{"role":"user","content":"' + text + '"}]}'
# ✓ 交給 JSON 序列化處理跳脫字元
import json
body = json.dumps({
"model": "MODEL_ID",
"messages": [{"role": "user", "content": text}],
}, ensure_ascii=False)若你的輸入來自使用者，內容中的引號與換行必須正確跳脫，這也是 400 的常見來源。
修正後仍失敗？
請確認：
- 你送出的欄位確實被瓜瓜AI 支援（未支援的參數可能導致 400，見 Chat Completions）。
- 你用的是正確的端點路徑（
/v1/chat/completions）。 - 內容長度未超過上限。