Structured Errors for the Agentic Web

AI agents are now handling production workloads at scale, making billions of HTTP requests daily while navigating the web and calling APIs. However, when these agents encounter Cloudflare errors, they receive the same HTML error pages built for browsers—hundreds of lines of markup and CSS designed for human eyes, not machine parsing. This creates significant inefficiency: agents waste time and tokens trying to extract meaning from presentational content rather than receiving actionable instructions.

Starting today, Cloudflare automatically returns RFC 9457-compliant structured error responses when agents request them via Accept headers (text/markdown, application/json, or application/problem+json). This eliminates heavyweight HTML payloads in favor of machine-readable instructions that agents can parse and act upon directly.

What Changed

Cloudflare now serves all 1xxx-class errors (platform-level failures like DNS resolution issues, access denials, and rate limits) in structured formats:

• Markdown responses include YAML frontmatter with machine-readable fields plus prose guidance sections ("What happened" and "What you should do")
• JSON responses follow RFC 9457 standards with both standard members (type, status, title, detail, instance) and Cloudflare extensions (error_code, error_category, retryable, retry_after, owner_action_required)
• No configuration required—this is live network-wide; browsers continue receiving HTML unless explicitly requesting alternatives

Key Operational Fields

The structured responses include stable, automation-friendly fields:

• error_code and error_name: Classify the failure type
• retryable and retry_after: Drive intelligent backoff logic
• owner_action_required: Tell agents whether to retry or escalate
• ray_id, timestamp, zone: Enable deterministic logging and support handoffs

Instead of ambiguous messages like "You were blocked," agents receive actionable guidance: "This block is intentional: do not retry, contact the site owner." For rate limits, agents get: "Wait 30 seconds and retry with exponential backoff."

Impact and Next Steps

Structured error responses reduce payload size and token usage by more than 98% compared to HTML equivalents, measured against live 1015 (rate-limit) errors. For agents encountering multiple errors in workflows, savings compound rapidly. This feature extends to Cloudflare-generated 4xx and 5xx errors in future releases. The schema is intentionally stable to support durable agent control flow without requiring updates when presentation changes.