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

claudejamodel: claude-sonnet-4-20250514

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

2026-03-11 Sam Marsh 7分で読める

AIエージェントはもはや実験ではありません。これらは本番インフラストラクチャとして、1日に数十億のHTTPリクエストを行い、ウェブをナビゲートし、APIを呼び出し、複雑なワークフローを調整しています。しかし、これらのエージェントがエラーに遭遇した際、依然としてブラウザ向けに構築された同じHTMLエラーページを受け取っています：人間の目のために設計された数百行のマークアップ、CSS、コピーです。

これらのページはエージェントに手がかりを与えますが、指示ではありません。そして時間とトークンを無駄にします。このギャップこそが、エージェントに障害ではなく指示を与える機会なのです。

本日より、CloudflareはAIエージェントに対してRFC 9457準拠の構造化MarkdownおよびJSONエラーペイロードを返し、重いHTMLページを機械可読な指示に置き換えます。これは、エージェントがAccept: text/markdown、Accept: application/json、またはAccept: application/problem+jsonを送信してCloudflareエラーに遭遇した際、HTMLの代わりに構造化フォーマットで1つのセマンティック契約を返すことを意味します。そして、実行可能なガイダンスが完備されています。

（これは最近のMarkdown for Agentsリリースに基づいています。）

そのため、単に「ブロックされました」と告げられる代わりに、エージェントは「レート制限されました — 30秒待機して指数バックオフで再試行してください」と読み取ります。単に「アクセス拒否」ではなく、エージェントは「このブロックは意図的です：再試行せず、サイト所有者に連絡してください」と指示されます。

これらのレスポンスは単により明確なだけでなく、劇的により効率的です。構造化エラーレスポンスは、ライブの1015（'rate-limit'）エラーレスポンスと比較して、ペイロードサイズとトークン使用量をHTMLに対して98%以上削減します。ワークフロー内で複数のエラーに遭遇するエージェントにとって、節約は急速に複利効果を生みます。

これはCloudflareネットワーク全体で自動的にライブです。サイト所有者は何も設定する必要がありません。ブラウザは以前と同じHTMLエクスペリエンスを受け取り続けます。

これらは単なるエラーページではありません。エージェンティックウェブのための指示なのです。

現在エージェントが見ているもの

エージェントがCloudflare生成のエラーを受信する場合、通常はCloudflareが顧客ポリシーを実行しているか、顧客に代わってプラットフォームレスポンスを返していることを意味します — Cloudflareがダウンしているわけではありません。

これらのレスポンスは、無効なホストやDNSルーティング、顧客定義のアクセス制御（WAF、地理的、ASN、またはボットルール）、レート制限などのエッジ強制制限など、リクエストがそのまま提供できない場合にトリガーされます。

要するに、Cloudflareは顧客のルーティングおよびセキュリティレイヤーとして機能し、レスポンスはリクエストがブロックされた理由や進行できない理由を説明します。

現在、これらのレスポンスは人間向けに設計された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エラーを適切に処理したい場合、選択肢は限られていました。Cloudflare生成エラーの場合、構造化レスポンスは設定依存パスにのみ存在し、エージェントの一貫したデフォルトとしては存在しませんでした。

Custom Error Rulesは一部の1xxxケースを含む多くのCloudflareエラーをカスタマイズできます。しかし、これらはサイトごとの設定に依存するため、ウェブ全体での汎用エージェント契約として機能できません。

Cloudflareはリクエストパスの前に位置します。つまり、デフォルトのマシンレスポンスを定義できます：再試行または停止、待機とバックオフ、エスカレーションまたは再ルーティング。エラーページは装飾ではなく実行指示になります。

私たちが行ったこと

Cloudflareは現在、すべての1xxxクラスエラーパス — DNS解決問題、アクセス拒否、レート制限などのエッジサイド障害に対するCloudflareのプラットフォームエラーコード — に対してRFC 9457準拠の構造化レスポンスを返します。

両方のフォーマットがライブです：

Accept: text/markdownはMarkdownを返します
Accept: application/jsonはJSONを返します
Accept: application/problem+jsonはapplication/problem+jsonコンテンツタイプでJSONを返します

これは現在すべての1xxxクラスエラーをカバーしています。同じ契約は次にCloudflare生成の4xxおよび5xxエラーに拡張されます。

Markdownレスポンスには2つの部分があります：

YAMLフロントマター：機械可読フィールド用
散文セクション：明示的なガイダンス用（What happenedとWhat you should do）

JSONレスポンスは同じフィールドをフラットオブジェクトとして運びます。

YAMLフロントマターは自動化の重要なレイヤーです。エージェントがHTMLをスクレイピングしたりコピーから意図を推測したりすることなく、安定したキーを抽出できます。

error_code、error_name、error_categoryなどのフィールドはエージェントが障害を分類できます
retryableとretry_afterはバックオフロジックを駆動します
owner_action_requiredはエージェントに継続試行かエスカレーションかを伝えます
ray_id、timestamp、zoneはログとサポート引き継ぎを決定論的にします

スキーマは設計により安定しているため、エージェントはプレゼンテーション変更を追跡することなく持続可能な制御フローを実装できます。

その安定性はCloudflareの発明ではありません。RFC 9457 — Problem Details for HTTP APIsは、HTTP上でエラーを報告するための標準JSON形状を定義し、クライアントが事前に特定のAPIを知ることなくエラーレスポンスを解析できます。

私たちのJSONレスポンスはこの形状に従います。つまり、Problem Detailsを理解するHTTPクライアントは、Cloudflare固有のコードなしでベースメンバーを解析できます：

RFC 9457メンバー	含まれる内容
`type`	特定のエラーコードに対するCloudflareのドキュメントを指すURI
`status`	HTTPステータスコード（実際のレスポンスステータスと一致）
`title`	問題の短い人間可読要約
`detail`	この発生に特有の人間可読説明
`instance`	この特定のエラー発生を識別するRay ID

運用フィールド — error_code、error_category、retryable、retry_after、owner_action_requiredなど — はRFC 9457拡張メンバーです。これらを認識しないクライアントは単にそれらを無視します。

これはネットワーク全体で追加的です。サイト所有者は何も設定する必要がありません。クライアントが明示的にMarkdownまたはJSONを要求しない限り、ブラウザはHTMLを受信し続けます。

レスポンスの外観

レート制限エラー（1015）の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：

---
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.

両方のフォーマットは、エージェントが決定し行動するために必要なすべてを提供します：エラーの分類、再試行動作の選択、エスカレーションが必要かどうかの判断。

これがデフォルトのマシン契約の外観です — サイトごとの設定ではなく、ネットワーク全体の動作です。

対比はエラーファミリー間で明示的です：1015のような一時的エラーは待機と再試行を指示し、1020や1009のような地理的制限のような意図的ブロックはエージェントに再試行せずエスカレーションするよう伝えます。

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を受け取ります — 同じボディ、既存コンシューマーの安全なデフォルト

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

その契約は置き換えるものより劇的に小さくもあります。CloudflareのHTMLエラーページはブラウザ指向で重い一方、構造化レスポンスは設計により軽量です。

1015の測定比較：

ペイロード	バイト	トークン (cl100k_base)	HTMLに対するサイズ	HTMLに対するトークン
HTMLレスポンス	46,645	14,252	—	—
Markdownレスポンス	798	221	58.5倍少ない	64.5倍少ない
JSONレスポンス	970	256	48.1倍少ない	55.7倍少ない

両方の構造化フォーマットは、HTMLに対してサイズとトークンで約98%の削減を実現します。エージェントにとって、サイズは直接トークンコストに変換されます — エージェントが1回の実行で複数のエラーに遭遇する場合、これらの節約はより低いモデル支出とより高速な回復ループに複利効果をもたらします。

10のカテゴリ、明確なアクション

すべての1xxxエラーはerror_categoryにマップされます。これにより、エラー処理は脆弱なページごとの解析ではなくルーティングロジックになります。

カテゴリ	意味	エージェントが取るべき行動
`access_denied`	意図的ブロック：IP、ASN、地理的、ファイアウォールルール	再試行しない。予期しない場合はサイト所有者に連絡
`rate_limit`	リクエストレート超過	バックオフ。retry_after秒後に再試行
`dns`	オリジンでのDNS解決失敗	再試行しない。サイト所有者に報告
`config`	設定エラー：CNAME、トンネル、ホストルーティング	再試行しない（通常）。サイト所有者に報告
`tls`	TLSバージョンまたは暗号の不一致	TLSクライアント設定を修正。そのまま再試行しない
`legal`	DMCAまたは規制ブロック	再試行しない。これは法的制限
`worker`	Cloudflare Workersランタイムエラー	再試行しない。サイト所有者がスクリプトを修正する必要
`rewrite`	無効なURL書き換え出力	再試行しない。サイト所有者がルールを修正する必要
`snippet`	Cloudflare Snippetsエラー	再試行しない。サイト所有者がSnippets設定を修正する必要
`unsupported`	サポートされていないメソッドまたは非推奨機能	リクエストを変更。そのまま再試行しない

2つのフィールドがエージェントにとって運用上有用にします：

retryable：再試行が成功するかどうかを答える
owner_action_required：問題をエスカレーションする必要があるかどうかを答える

脆弱な「if status == 429 then maybe retry」ヒューリスティックを明示的な制御フローに置き換えることができます。フロントマターを一度解析し、その後分岐します。

Summary