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 inretry_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:
curl -s --compressed -H "Accept: application/json" -A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" "<YOUR_DOMAIN>/cdn-cgi/error/522" | jq .Check presence of the Retry-After HTTP header associated with the JSON response for error 521:
curl -s --compressed -D - -o /dev/null -H "Accept: application/json" -A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" "<YOUR_DOMAIN>/cdn-cgi/error/521" | grep -i retry-afterReferences:
Source: Cloudflare
