CF-Incidents Cloudflare Fundamentals - JSON responses and RFC 9457 support for Cloudflare 1xxx errors

[ENF News Bot]

Cloudflare-generated 1xxx errors now return structured JSON when clients send Accept: application/json or Accept: application/problem+json. JSON responses follow RFC 9457 (Problem Details for HTTP APIs) ↗︎, so any HTTP client that understands Problem Details can parse the base members without Cloudflare-specific code.

Breaking change​

https://developers.cloudflare.com/changelog/rss/#breaking-change

The Markdown frontmatter field http_status has been renamed to status. Agents consuming Markdown frontmatter should update parsers accordingly.

Changes​

https://developers.cloudflare.com/changelog/rss/#changes

JSON format. Clients sending Accept: application/json or Accept: application/problem+json now receive a structured JSON object with the same operational fields as Markdown frontmatter, plus RFC 9457 standard members.

RFC 9457 standard members (JSON only):

• type — URI pointing to Cloudflare documentation for the specific error code
• status — HTTP status code (matching the response status)
• title — short, human-readable summary
• detail — human-readable explanation specific to this occurrence
• instance — Ray ID identifying this specific error occurrence

Field renames:

• http_status -> status (JSON and Markdown)
• what_happened -> detail (JSON only — Markdown prose sections are unchanged)

Content-Type mirroring. Clients sending Accept: application/problem+json receive Content-Type: application/problem+json; charset=utf-8 back; Accept: application/json receives application/json; charset=utf-8. Same body in both cases.

Negotiation behavior​

https://developers.cloudflare.com/changelog/rss/#negotiation-behavior

Request header sent	Response format
Accept: application/json	JSON (application/json content type)
Accept: application/problem+json	JSON (application/problem+json content type)
Accept: application/json, text/markdown;q=0.9	JSON
Accept: text/markdown	Markdown
Accept: text/markdown, application/json	Markdown (equal q, first-listed wins)
Accept: */*	HTML (default)

Availability​

https://developers.cloudflare.com/changelog/rss/#availability

Available now for Cloudflare-generated 1xxx errors.

Get started​

https://developers.cloudflare.com/changelog/rss/#get-started

curl -s --compressed -H "Accept: application/json" -A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" "<YOUR_DOMAIN>/cdn-cgi/error/1015" | jq .

curl -s --compressed -H "Accept: application/problem+json" -A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" "<YOUR_DOMAIN>/cdn-cgi/error/1015" | jq .

References:

• RFC 9457 — Problem Details for HTTP APIs ↗︎
• Cloudflare 1xxx error documentation

Continue reading...