Cloudflare Fundamentals - Structured error responses for…

Cloudflare-generated 5xx error responses now return structured JSON and Markdown when agents request them, matching the format already available for 1xxx errors. Responses follow RFC 9457 (Problem Details for HTTP APIs) and include a Retry-After HTTP header on retryable codes.

Changes

5xx coverage. Ten Cloudflare-generated error codes (500, 502, 504, 520-526) now serve structured responses. These are errors Cloudflare itself generates when it cannot reach or understand the origin server. Origin-generated 5xx responses that Cloudflare passes through are not affected.

Fault attribution. The error_category field tells agents where the fault lies:

origin (502, 504, 520-524) — the origin server is responsible. Transient; retry with the backoff in retry_after.
cloudflare (500) — Cloudflare's fault, not the website or the request. Short retry.
ssl (525, 526) — the origin's TLS configuration is broken. Do not retry.

Retry-After header. Retryable codes (500, 502, 504, 520-524) include a Retry-After HTTP header matching the retry_after body field. Non-retryable codes (525, 526) do not include the header.

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

Available now for all zones on all plans.

Get started

Get JSON response for error 522:

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

Check presence of the Retry-After HTTP header associated with the JSON response for error 521:

<div><div><span>curl</span><span> </span><span>-s</span><span> </span><span>--compressed</span><span> </span><span>-D</span><span> </span><span>-</span><span> </span><span>-o</span><span> </span><span>/dev/null</span><span> </span><span>-H</span><span> </span><span>"Accept: application/json"</span><span> </span><span>-A</span><span> </span><span>"TestAgent/1.0"</span><span> </span><span>-H</span><span> </span><span>"Accept-Encoding: gzip, deflate"</span><span> </span><span>"<YOUR_DOMAIN>/cdn-cgi/error/521"</span><span> </span><span>|</span><span> </span><span>grep</span><span> </span><span>-i</span><span> </span><span>retry-after</span></div></div>

References:

Cloudflare Fundamentals - Structured error responses for Cloudflare 5xx errors