Machine-Readable Errors for Production Agents

AI agents now operate as production infrastructure at scale, making billions of HTTP requests daily. However, when agents encounter Cloudflare errors, they have historically received HTML error pages designed for human browsers—hundreds of lines of markup that waste tokens and provide no machine-actionable guidance. Starting today, Cloudflare returns structured, RFC 9457-compliant error responses when agents request them via Accept: text/markdown, Accept: application/json, or Accept: application/problem+json.

What Changed

Structured response formats replace heavyweight HTML with semantic contracts. Instead of opaque messages like "You were blocked," agents now receive actionable instructions: "This block is intentional: do not retry, contact the site owner." The new responses include:

• YAML frontmatter with machine-readable fields: error_code, error_name, error_category, retryable, retry_after, owner_action_required, ray_id, timestamp, and zone
• RFC 9457 standard fields (type, status, title, detail, instance) that any HTTP client understanding Problem Details can parse natively
• Prose guidance with explicit "What happened" and "What you should do" sections

The schema is stable and backwards-compatible. Browsers continue receiving HTML responses unless they explicitly request alternatives. This rollout covers all 1xxx-class error paths (Cloudflare platform errors like DNS resolution failures, access denials, and rate limits), with 4xx and 5xx errors coming next.

Impact and Developer Action

Structured responses achieve 98% reduction in payload size and token usage versus HTML—measured against live rate-limit (1015) errors. For agents hitting multiple errors in a workflow, savings compound significantly.

Developers can act immediately: AI agents that support Accept headers will automatically receive structured responses without configuration changes. For custom error handling, implement parsing logic for the stable YAML/JSON fields to drive control flow (retry backoff, escalation logic, etc.). No site owner configuration is required; responses are live network-wide.