DocsDigest
Back to listLanguage: JA
OpenAICloudflareMar 11, 2026, 1:05 PM

Slashing agent token costs by 98% with RFC 9457-compliant error responses

A condensed section focused on the key takeaways first.

Original Post
OpenAIClaude

Quick Digest

Summary

A condensed section focused on the key takeaways first.

openaienmodel: gpt-5-mini-2025-08-07

Slashing agent token costs by 98% with RFC 9457-compliant error responses

rfc9457error-handlingagentsjsonmarkdownrate-limitingcloudflare

Key Points

  • RFC 9457 JSON/Markdown error responses for 1xxx errors
  • ~98% payload and token reduction versus HTML
  • Network-wide default; no site configuration required

Summary

Cloudflare now returns RFC 9457-compliant structured error responses (Markdown and JSON/application/problem+json) for all 1xxx-class edge errors. Agents that send Accept: text/markdown, Accept: application/json, or Accept: application/problem+json receive compact, machine-readable payloads with stable fields (e.g., error_code, error_name, error_category, retryable, retry_after, owner_action_required, ray_id, timestamp, zone). This is network-wide, requires no site configuration, and keeps browser HTML unchanged.

Key Points

  • Two wire formats:
    • text/markdown: YAML frontmatter + prose sections ("What Happened" / "What You Should Do")
    • application/json or application/problem+json: RFC 9457-compatible JSON with the same operational fields
  • Operational fields to drive agent logic:
    • error_category: maps errors to deterministic handler (rate_limit, access_denied, dns, tls, etc.)
    • retryable (bool) and retry_after (seconds): direct backoff guidance
    • owner_action_required (bool): escalate vs. continue
    • ray_id, timestamp, zone: deterministic observability and handoff
  • Behavior and compatibility:
    • Clients that don't recognize extension members ignore them (RFC 9457 extensions are additive)
    • Browsers still receive the legacy HTML unless a client explicitly requests JSON/Markdown
    • No per-site configuration required; the contract is network-wide and stable

Practical guidance for engineers

  • Parse the YAML frontmatter (or JSON fields) once at the edge of your agent pipeline to extract: error_code, retryable, retry_after, owner_action_required, error_category.
  • Implement control flow based on fields instead of brittle status-code heuristics:
    • If retryable == true: wait retry_after seconds and apply exponential backoff; stop after configured retry limit.
    • If owner_action_required == true or error_category in {access_denied, legal, config}: do not retry; escalate to site owner or log for human action.
    • Use error_category to route handling logic (e.g., rate_limit -> backoff, dns/config -> report/stop).
  • Prefer application/problem+json for standard HTTP client libraries; use text/markdown if your parser favors frontmatter + human-readable guidance.

Size and cost impact

  • Example (Error 1015, rate limit):
    • HTML: 46,645 bytes (~14,252 tokens)
    • Markdown: 798 bytes (~221 tokens)
    • JSON: 970 bytes (~256 tokens)
  • Structured formats reduce payload size and token usage by ~98% vs. HTML, lowering model costs and speeding agent recovery when multiple errors occur.

Implementation notes

  • The JSON follows RFC 9457 base members (type, title, status, detail, instance) and exposes Cloudflare-specific extension members for operational behavior.
  • Treat extension members as authoritative for agent control flow; unknown fields can be ignored for forward compatibility.

Bottom line

Switch agent error handling to parse the provided frontmatter/JSON fields and implement deterministic retry/escalation policies based on retryable, retry_after, owner_action_required, and error_category. This yields predictable behavior and substantial token/cost savings.

Full Translation

Translations

A translation section that keeps the flow of the original article.

openaijamodel: gpt-5-mini-2025-08-07

RFC 9457 準拠のエラー応答でエージェントのトークンコストを98%削減

概要

AI エージェントはもはや実験段階ではなく、日々何十億もの HTTP リクエストを送り、ウェブを巡回し、API を呼び出し、複雑なワークフローをオーケストレーションする本番インフラです。しかし、エージェントがエラーに遭遇したとき、今までブラウザ向けに作った HTML エラーページ（数百行のマークアップ、CSS、メッセージ）を受け取っていました。これらはエージェントにとって「手がかり」にはなるものの、実行指示ではなく、トークンと時間の無駄遣いです。

Cloudflare は本日より、AI エージェント向けに RFC 9457 準拠の構造化された Markdown と JSON のエラーペイロードを返し、重い HTML ページを機械可読な指示に置き換えます。Accept: text/markdown、Accept: application/json、Accept: application/problem+json のいずれかを送信したクライアントが Cloudflare のエラーに遭遇した場合、HTML の代わりに一つの意味論的契約（structured format）を返し、実行可能なガイダンスを含みます。

このアプローチにより、単に「ブロックされました」と伝えるのではなく、例えば「レート制限されています — 30 秒待ち、指数バックオフでリトライしてください」のように、エージェントにとって実行可能な指示が与えられます。構造化エラー応答は、HTML と比べてペイロードサイズとトークン使用量を 98% 以上削減します（ライブの 1015（'rate-limit'）エラー応答で計測）。ワークフロー中に複数回エラーが発生する場合、この節約は急速に累積します。

これらはネットワーク全体で自動的に有効です。サイトオーナーの設定は不要で、ブラウザは従来どおり HTML を受け取り続けます。これは単なるエラーページではなく、エージェント化されたウェブのための実行指示です。

現状（エージェントが見ているもの）

Cloudflare が生成するエラーは、多くの場合 Cloudflare 自体の障害ではなく、リクエストをそのまま提供できない（無効なホストや DNS ルーティング、顧客定義のアクセス制御（WAF、ジオ、ASN、ボットルール）、エッジで強制される制限など）ために発生します。現在、これらの応答は人間向けにレンダリングされた HTML です。例:

<!DOCTYPE html>
<html>
<head>
<title>Access denied | example.com used Cloudflare to restrict access</title>
<style>/* 200 lines of CSS */</style>
</head>
<body>
<div class="cf-wrapper">
<h1 data-translate="block_headline">Sorry, you have been blocked</h1>
<!-- ... hundreds more lines ... -->
</div>
</body>
</html>

エージェントにとってこれはほぼノイズで、どのエラーが起きたのか、なぜブロックされたのか、リトライが有効かどうかを判断できません。HTML をパースできたとしても、次に何をすべきか（人間にも機械にも）は明示されていません。

エージェント開発者が Cloudflare エラーに優雅に対応するには選択肢が限られていました。Structured responses は、サイトごとの設定に依存するパスには存在しましたが、エージェント向けの一貫したデフォルトにはなっていませんでした。Custom Error Rules で多くの 1xxx エラーをカスタマイズできますが、サイトごとの設定に依存するため、ウェブ全体の共通契約にはなりえません。

Cloudflare はリクエスト経路の前段に位置するため、デフォルトの機械応答を定義できます: retry するか停止するか、待ってバックオフするか、エスカレーションまたはルーティングを変更するか。エラーページが装飾ではなく実行指示になります。

Cloudflare の対応（何をしたか）

Cloudflare はすべての 1xxx クラスのエラー経路（DNS 解決問題、アクセス拒否、レート制限などのエッジ側失敗を表すプラットフォームエラー）に対して RFC 9457 準拠の構造化応答を返します。形式は両方サポートされています:

  • Accept: text/markdown は Markdown を返す
  • Accept: application/json は JSON を返す
  • Accept: application/problem+json は application/problem+json の Content-Type で JSON を返す

これは現時点で全ての 1xxx クラスエラーをカバーしています。将来的には Cloudflare が生成する 4xx/5xx エラーにも同じ契約を拡張します。

Markdown 応答は二部構成です:

  • YAML frontmatter（機械可読フィールド）
  • 明示的なガイダンスのための本文（"What happened" と "What you should do"）

JSON 応答は同じフィールドをフラットなオブジェクトとして持ちます。YAML frontmatter は自動化にとって重要な層で、エージェントは HTML をスクレイピングしたりコピーから意図を推測したりせずに安定したキーを抽出できます。

フィールド例: error_code, error_name, error_category, retryable, retry_after, owner_action_required, ray_id, timestamp, zone, cloudflare_error など。これらにより、エージェントは失敗を分類し、バックオフロジックを決定し、エスカレーションが必要かどうかを判断できます。スキーマは意図的に安定化されているため、プレゼンテーションの変更を追いかける必要がありません。

この安定性自体は Cloudflare の独自発明ではありません。RFC 9457 — Problem Details for HTTP APIs は HTTP 上でエラーを報告するための標準 JSON 形状を定義しており、クライアントは事前に特定の API を知らなくてもエラー応答をパースできます。Cloudflare の JSON 応答はこの形状に従い、以下の基本メンバーは問題詳細を理解するためにそのまま使えます:

  • type: Cloudflare の特定エラーコードに関するドキュメントへの URI
  • status: 実際のレスポンスステータスと一致する HTTP ステータスコード
  • title: 問題の短い人間向け概要
  • detail: この発生に特有の人間向け説明
  • instance: この特定の発生を識別する一意の値（Ray ID と一致することが多い）

運用フィールド（error_code, error_category, retryable, retry_after, owner_action_required など）は RFC 9457 の拡張メンバーです。これらを知らないクライアントは単に無視できます。

この変更はネットワーク全体で追加的（additive）であり、サイトオーナー側の設定は不要です。ブラウザは明示的に Markdown または JSON を要求しない限り従来の HTML を受け取り続けます。

応答の例（1015 rate-limit）

JSON 例:

{
    "type": "https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1015/",
    "title": "Error 1015: You are being rate limited",
    "status": 429,
    "detail": "You are being rate-limited by the website owner's configuration.",
    "instance": "9d99a4434fz2d168",
    "error_code": 1015,
    "error_name": "rate_limited",
    "error_category": "rate_limit",
    "ray_id": "9d99a4434fz2d168",
    "timestamp": "2026-03-09T11:11:55Z",
    "zone": "<YOUR_DOMAIN>",
    "cloudflare_error": true,
    "retryable": true,
    "retry_after": 30,
    "owner_action_required": false,
    "what_you_should_do": "**Wait and retry.** This block is transient. Wait at least 30 seconds, then retry with exponential backoff.\n\nRecommended approach:\n1. Wait 30 seconds before your next request\n2. If rate-limited again, double the wait time (60s, 120s, etc.)\n3. If rate-limiting persists after 5 retries, stop and reassess your request pattern",
    "footer": "This error was generated by Cloudflare on behalf of the website owner."
}

同じエラーをモデルファーストワークフロー向けに最適化した Markdown 例（YAML frontmatter を含む）:

---
error_code: 1015
error_name: rate_limited
error_category: rate_limit
status: 429
ray_id: 9d99a39dc992d168
timestamp: 2026-03-09T11:11:28Z
zone: <YOUR_DOMAIN>
cloudflare_error: true
retryable: true
retry_after: 30
owner_action_required: false
---
# Error 1015: You are being rate limited
## What Happened
You are being rate-limited by the website owner's configuration.
## What You Should Do
**Wait and retry.** This block is transient. Wait at least 30 seconds, then retry with exponential backoff.
Recommended approach:
1. Wait 30 seconds before your next request
2. If rate-limited again, double the wait time (60s, 120s, etc.)
3. If rate-limiting persists after 5 retries, stop and reassess your request pattern
---
This error was generated by Cloudflare on behalf of the website owner.

両フォーマットは、エージェントが失敗を分類し、リトライ動作を選び、エスカレーションが必要かどうかを判断するのに十分な情報を与えます。これはサイトごとの設定ではなく、ネットワーク全体のデフォルトの機械契約です。

1つの契約、2 つのフォーマット

価値はフォーマットの選択肢ではなく意味論的安定性にあります。エージェントは次の運用上の疑問に対して決定論的な答えを必要とします: リトライすべきか、どれくらい待つべきか、エスカレーションすべきか。

Cloudflare は 2 つのワイヤ形式で 1 つのポリシー契約を公開します。Markdown でも JSON でも、運用上の意味は同一です。 Accept: application/problem+json を送信したクライアントには application/problem+json; charset=utf-8 が返り、HTTP クライアントライブラリがメディアタイプで分岐するのに便利です。Accept: application/json を送ると application/json; charset=utf-8 が返ります。

サイズ削減とトークン効率

この契約は置き換えるものよりも圧倒的に小さくなります。HTML はブラウザ向けで重く、構造化応答はコンパクトです。1015 の比較（計測）:

ペイロードBytesTokens (cl100k_base)サイズ比（HTML）トークン比（HTML）
HTML response46,64514,252——
Markdown response79822158.5x less64.5x less
JSON response97025648.1x less55.7x less

両方の構造化フォーマットは HTML と比べて約 98% の削減を実現します。エージェントにとってサイズはそのままトークンコストに直結するため、ワークフロー内で複数回エラーが発生すると、こうした節約はモデルへの支出削減と高速なリカバリループにつながります。

10 カテゴリと明確な行動

すべての 1xxx エラーは error_category にマップされ、エラー処理はページごとの壊れやすいパースではなくルーティングロジックになります。

Category意味エージェントが行うべきこと
access_denied意図的なブロック（IP, ASN, 国別制限, firewall rule 等）リトライしない。予期せず発生した場合はサイトオーナーに連絡。
rate_limitリクエストレート超過バックオフ。retry_after 秒待ってリトライ。
dnsオリジンでの DNS 解決失敗リトライしない。サイトオーナーに報告。
config設定エラー（CNAME, トンネル, ホストルーティング等）通常はリトライしない。サイトオーナーに報告。
tlsTLS バージョンまたは暗号の不整合TLS クライアント設定を修正。現状のままリトライしない。
legalDMCA や法的な制限リトライしない。法的制限。
workerCloudflare Workers のランタイムエラーリトライしない。サイトオーナーがスクリプトを修正する必要あり。
rewrite無効な URL rewrite 出力リトライしない。サイトオーナーがルールを修正する必要あり。
snippetCloudflare Snippets のエラーリトライしない。サイトオーナーが Snippets 設定を修正する必要あり。
unsupportedサポートされないメソッドや非推奨機能リクエストを変更する。現状のままリトライしない。

この一覧を実用的にする 2 つのフィールド:

  • retryable はリトライが成功する可能性があるかを示す
  • owner_action_required は問題がエスカレーション（サイトオーナーの介入）を必要とするかを示す

これにより「if status == 429 then maybe retry」のような壊れやすいヒューリスティックを、フロントマターを一度パースして明確な制御フローに置き換えられます。フロントマターを一度解析し、error_category や retryable、retry_after、owner_action_required に基づいて分岐処理を行えば、安定したエラー処理が可能です。

まとめ

Cloudflare の RFC 9457 準拠の構造化エラー応答は、エージェントに対して明確で機械可読、かつ小さい応答を提供します。これによりトークンコストが大幅に削減され、エージェントは決定論的な制御フローでエラーに対処できるようになります。ネットワーク全体で自動的に有効化され、サイトオーナーの追加設定は不要です。