5xx 上游錯誤

5xx 代表伺服器端發生錯誤。以瓜瓜AI 這類代理上游模型服務的架構而言，5xx 通常表示上游服務暫時異常、逾時或過載——不是你的請求寫錯。

標準語意

5xx 屬於伺服器錯誤，通常具暫時性，適合間隔後重試。與 4xx 不同，重試同樣的請求是合理的。

常見子類型

狀態碼	名稱	常見意義
`500`	Internal Server Error	服務內部非預期錯誤
`502`	Bad Gateway	閘道無法從上游取得有效回應
`503`	Service Unavailable	服務暫時無法處理（過載或維護）
`504`	Gateway Timeout	等待上游回應逾時

待補充

瓜瓜AI 在各種上游異常下實際回傳的狀態碼與錯誤主體格式尚待官方確認，是否提供重試建議標頭亦未確認。

排查步驟

1. 確認是持續性或偶發性

bash

for i in 1 2 3; do
  curl -o /dev/null -s -w "%{http_code}\n" \
    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"}]}'
  sleep 2
done

結果	判讀	處理
出現 `200`	偶發性	加入重試機制即可
全部 5xx	持續性	稍後再試，並考慮回報
混合出現	上游不穩定	重試＋監控

2. 區分逾時與錯誤

症狀	可能原因
`504` 或連線逾時	請求內容過長、上游回應慢
`502` / `503`	上游服務異常或過載
`500`	服務內部錯誤
完全無回應	網路、Proxy、防火牆問題（非 5xx）

3. 排除自身因素

雖然 5xx 是伺服器問題，但以下情況可能間接導致上游失敗：

因素	說明
請求內容過長	超過模型可處理長度，可能導致上游逾時
逾時設定過短	客戶端提早放棄，看起來像失敗
串流時間過長	長回應可能觸發平台或代理逾時
代理緩衝	中間層等待過久導致 504

重試策略

5xx 適合重試，但要避免重試風暴：

python

import random
import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.guagua5487.xyz/v1",
    timeout=60.0,
)

RETRYABLE = {500, 502, 503, 504}

def chat(prompt: str, attempts: int = 4) -> str:
    for i in range(attempts):
        try:
            resp = client.chat.completions.create(
                model="MODEL_ID",
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.choices[0].message.content or ""
        except APIStatusError as e:
            if e.status_code not in RETRYABLE or i == attempts - 1:
                raise
            time.sleep(min(2 ** i, 20) + random.uniform(0, 0.5))
        except APIConnectionError:
            if i == attempts - 1:
                raise
            time.sleep(min(2 ** i, 20) + random.uniform(0, 0.5))
    return ""

原則	說明
只重試可重試的狀態碼	`429` 與 `5xx`；`4xx` 重試無用
指數退避＋抖動	避免多個客戶端同時重試
設定重試上限	通常 3～5 次
保留最後錯誤	方便記錄與回報
串流另案處理	串流中斷無法續傳，見串流輸出

使用者體驗建議

情境	建議
短暫失敗	對使用者顯示「正在重試」，避免直接報錯
重試仍失敗	顯示友善訊息，並提供稍後再試的選項
串流中斷	保留已顯示內容，提供「重新產生」按鈕
長時間異常	考慮切換備援模型（若你已確認可用清單）

回報問題時請提供

發生時間（含時區）
HTTP 狀態碼與完整回應主體
使用的模型代號
是否為串流請求
請求是否可重現
回應中的請求 ID（若有）

請勿提供金鑰

回報時請以 YOUR_API_KEY 取代真實金鑰。若回應主體中意外包含敏感資訊，請先遮蔽。

5xx 上游錯誤 ​

常見子類型 ​

排查步驟 ​

1. 確認是持續性或偶發性 ​

2. 區分逾時與錯誤 ​

3. 排除自身因素 ​

重試策略 ​

使用者體驗建議 ​

回報問題時請提供 ​

相關頁面 ​