Markdown Error Responses Now Available

Cloudflare has introduced support for structured Markdown responses for Cloudflare-generated 1xxx errors. Clients can opt-in by sending Accept: text/markdown in their request headers, enabling more efficient error handling and parsing for automated systems.

Response Format and Metadata

Each Markdown response includes comprehensive structured data via YAML frontmatter and two guidance sections:

• Frontmatter fields: error_code, error_name, error_category, http_status, ray_id, timestamp, zone, cloudflare_error, retryable, retry_after, and owner_action_required
• Guidance sections: "What happened" and "What you should do" to enable deterministic retry and escalation decisions without HTML parsing

Performance Impact

In measured tests across 1,015 comparisons, Markdown responses reduced payload size and token footprint by over 98% compared to HTML error pages. This significantly improves efficiency for agents and automated systems processing errors.

Content Negotiation

Cloudflare uses standard HTTP content negotiation on the Accept header:

• Accept: text/markdown → Markdown response
• Accept: text/markdown, text/html;q=0.9 → Markdown response
• Accept: text/* → Markdown response
• Accept: */* → HTML response (default)

When multiple content types are specified, Cloudflare selects the highest-priority supported media type using quality (q) values. If Markdown is not explicitly preferred, HTML is returned.

Getting Started

To receive Markdown error responses, include the Accept: text/markdown header in your requests:

curl -H "Accept: text/markdown" https://<your-domain>/cdn-cgi/error/1015

Default behavior remains unchanged—clients that do not explicitly request Markdown continue to receive HTML error pages. Full documentation on Cloudflare 1xxx errors is available in the error reference guide.