Cloudflare の 5xx エラーが構造化 JSON で返ってくるようになったよ！

やっほー、しぃちゃんだよ！今日はサーバーのエラー応答がちょっと賢くなるお話。エージェント時代にぴったりのアップデートだよ。

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog で、Cloudflare が生成する 5xx エラー応答が、構造化された JSON と Markdown で返せるようになったって発表があったの。これは 1xxx エラー向けにもう用意されていた仕組みを 5xx にも広げたものなんだ。応答は RFC 9457（Problem Details for HTTP APIs） に沿っていて、リトライ可能なコードには Retry-After ヘッダーも付くよ。

今までどうだったの？

これまで 5xx のエラーページは、基本的に人間が読むための HTML だったの。ブラウザで見る分にはいいんだけど、自動でリクエストを投げるエージェントやスクリプトからすると、「何が起きて、リトライしていいのか」を HTML から読み取るのは大変だったんだよね。

これで何が変わるの？

対象は Cloudflare 自身が生成する 10 個のコード（500、502、504、520〜526）。Cloudflare がオリジンに届かない・理解できないときに出すエラーが対象で、オリジンが返してそのまま通過する 5xx は対象外なの。

うれしいのは error_category フィールドで「どこが悪いのか」がわかること。エージェントは中身を見て、リトライすべきか止めるべきかを機械的に判断できるようになるよ。

深く潜ってみよう

error_category は 3 種類に分かれるの。

• origin（502、504、520〜524）: オリジン側の問題。一時的なものだから retry_after のバックオフでリトライしてね。
• cloudflare（500）: Cloudflare 側の問題。短めのリトライを。
• ssl（525、526）: オリジンの TLS 設定が壊れてる。これはリトライしちゃダメ。

Retry-After ヘッダーはリトライ可能なコード（500、502、504、520〜524）に付いて、本文の retry_after と一致するよ。リトライしても意味がない 525・526 には付かないの。

どの形式で返すかは Accept ヘッダーで決まるよ。application/json や application/problem+json なら JSON、text/markdown なら Markdown、*/* なら今まで通り HTML。複数指定したときは q 値の大きいほうが優先で、同じ q なら先に書いたほうが勝つんだって。

試すときはこんな感じ。エラー 522 の JSON を取るなら:

curl -s --compressed -H "Accept: application/json" -A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" "https://example.com/cdn-cgi/error/522" | jq .

対応は全ゾーン・全プランで、もう使えるよ。詳しくは Cloudflare の 5xx エラーのドキュメント を見てね。

まとめ

• Cloudflare 生成の 5xx エラー（500、502、504、520〜526）が構造化 JSON / Markdown で返せるように
• error_category で origin / cloudflare / ssl の責任分界がわかる
• リトライ可能コードには Retry-After ヘッダー付き、525・526 には付かない
• 形式は Accept ヘッダーで交渉、全ゾーン・全プランで利用可能

自動リトライを組んでる人や、エージェント／スクリプトで Cloudflare 越しに外部 API を叩く devops な人に刺さるアップデートだよ！