觀點 · 資訊分享
Cloudflare 的 5xx 錯誤頁會「說人話」給程式看：10 種錯誤碼改回 JSON，還告訴你該不該重試
Cloudflare 讓自己產生的 10 種 5xx 錯誤，在程式或 AI Agent 要求時改回 JSON 或 Markdown，並標明是誰的錯、要不要重試。所有方案、所有網站都已經能用。
- 發布
- 2026-04-28
- 篇幅
- 約 4 分鐘 · 1,825 字
- 結構
- 8 節 + 3 題常見問題
- 標籤
一句話看懂：Cloudflare 讓自己產生的 10 種 5xx 錯誤，在程式要求時改回 JSON 或 Markdown，並標明是誰的錯、該不該重試。
先用白話講：5xx 錯誤是什麼？
你一定看過網站打不開、跳出「502 Bad Gateway」之類的畫面。5 開頭的數字代表「伺服器那邊出問題」，不是你的錯。
想像你打電話去餐廳訂位，如果對方只會回一長串口語抱怨，你得自己聽出「是客滿，還是電話壞了」。而 Cloudflare 這次的更新，就像櫃檯多準備了一張固定格式的表格：欄位寫明「原因分類」和「幾秒後再打」，讓程式一眼就能讀懂。
發生什麼事
Cloudflare 在 4 月 27 日的更新日誌宣布：Cloudflare 自己產生的 5xx 錯誤，現在會依請求方的要求，回結構化的 JSON 或 Markdown。這個做法先前已經用在 1xxx 系列錯誤，這次擴大到 5xx。
- 涵蓋 10 種錯誤碼：500、502、504，以及 520 到 526
- 這些都是「Cloudflare 連不上、或看不懂源站回應」時自己產生的錯誤
- 源站自己回的 5xx 不受影響，會原樣轉給訪客
- 回應格式遵循 RFC 9457（HTTP API 的標準錯誤格式）
- 所有方案、所有網站現在都能用
誰的錯？要不要重試？
新的 error_category 欄位把錯誤分成三類：
| 分類 | 對應錯誤碼 | 意思 | 建議 |
|---|---|---|---|
| origin | 502、504、520 到 524 | 源站該負責 | 暫時性問題，依 retry_after 的秒數重試 |
| cloudflare | 500 | Cloudflare 自己的問題 | 稍等短時間再試 |
| ssl | 525、526 | 源站的 TLS 設定壞了 | 不要重試，先修設定 |
可重試的錯誤碼還會多帶一個 Retry-After HTTP 標頭，數值和 JSON 裡的 retry_after 一致；525 與 526 則不帶這個標頭。
怎麼拿到結構化回應？
看請求送出的 Accept 標頭：
| Accept 標頭 | 回應格式 |
|---|---|
application/json |
JSON |
application/problem+json |
JSON（對應的內容類型） |
text/markdown |
Markdown |
text/markdown, application/json |
Markdown（同權重時，先列的優先） |
*/* |
HTML（維持預設） |
所以一般瀏覽器訪客看到的錯誤頁沒有變，只有主動要求的程式才會拿到新格式。
給開發者的技術細節
官方給了兩個測試指令，把 <YOUR_DOMAIN> 換成自己的網域：
# 取得錯誤 522 的 JSON 回應
curl -s --compressed -H "Accept: application/json" \
-A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" \
"<YOUR_DOMAIN>/cdn-cgi/error/522" | jq .
- 依
error_category分流：origin 類做指數退避重試；ssl 類直接告警，不要自動重試 - 呼叫別人網站的後端、爬蟲、AI Agent 都可以把
Accept: application/json加進預設標頭 - 官方只說明了 Cloudflare 自己產生的錯誤；你自己的源站回的錯誤格式，還是得自己處理
我的看法
我自己接案時，常遇到後端呼叫第三方 API、結果對方被 Cloudflare 擋在前面的情況。以前遇到 5xx，程式只能整頁 HTML 丟進 log，要人眼去看才知道是源站掛了還是憑證設定錯。有了 error_category，至少能做到「該重試的重試、不該重試的立刻告警」，少一點無意義的重試風暴。
另一個角度是 AI Agent：Agent 打 API 遇到錯誤時，如果拿到的是整頁 HTML，常常會讀錯。結構化回應對這種場景幫助很大。不過它只管 Cloudflare 自己產生的錯誤，自架服務的人別因此就覺得源站的錯誤處理可以省略。
名詞小辭典
- 5xx 錯誤：HTTP 狀態碼中 5 開頭的一類，代表伺服器端出了問題，而不是使用者操作錯誤。
- 源站（Origin）：真正放網站內容的那台伺服器；Cloudflare 站在它前面幫忙轉送與加速。
- RFC 9457：網路標準文件，規定 HTTP API 回報錯誤時的統一格式，讓不同服務的錯誤長得一樣。
- Retry-After：HTTP 標頭，告訴對方「請等幾秒再試一次」。