JA EN
shiichan

Cloudflare's 5xx Errors Now Come Back as Structured JSON!

Cloudflare Changelog ★★★ View Markdown
#cloudflare#web#devops

Hey everyone, it's Shiichan! Today's story is about server error responses getting a little smarter -- a nice fit for the age of agents.

Cloudflare Changelog developers.cloudflare.com

What was announced?

Over on the Cloudflare Changelog, they announced that Cloudflare-generated 5xx error responses can now come back as structured JSON and Markdown when agents ask for them. It extends the same mechanism that was already available for 1xxx errors. The responses follow RFC 9457 (Problem Details for HTTP APIs), and retryable codes also carry a Retry-After header.

The story so far

Until now, 5xx error pages were basically HTML meant for humans to read. That's fine in a browser, but for an agent or script firing requests automatically, pulling "what happened, and is it safe to retry?" out of HTML was a pain.

What changes

This covers ten codes that Cloudflare itself generates (500, 502, 504, 520-526). These are errors Cloudflare produces when it cannot reach or understand the origin -- origin-generated 5xx responses that Cloudflare merely passes through are not affected.

The nice part is the error_category field, which tells you where the fault lies. An agent can read the body and decide mechanically whether to retry or stop.

Dive Deep

error_category comes in three flavors:

  • origin (502, 504, 520-524) -- the origin is at fault. Transient, so retry using the backoff in retry_after.
  • cloudflare (500) -- Cloudflare's own fault. Do a short retry.
  • ssl (525, 526) -- the origin's TLS config is broken. Do not retry.

The Retry-After header is attached to retryable codes (500, 502, 504, 520-524) and matches the retry_after body field. The non-retryable 525 and 526 don't include it.

The format is chosen by your Accept header: application/json or application/problem+json gives JSON, text/markdown gives Markdown, and */* stays HTML as before. When you list several, the higher q value wins, and with equal q the first-listed one wins.

Here's how to try it. To grab JSON for error 522:

curl -s --compressed -H "Accept: application/json" -A "TestAgent/1.0" -H "Accept-Encoding: gzip, deflate" "https://example.com/cdn-cgi/error/522" | jq .

It's live now for all zones on all plans. For details, see the Cloudflare 5xx error documentation.

Wrap-up

  • Cloudflare-generated 5xx errors (500, 502, 504, 520-526) can now return structured JSON / Markdown
  • error_category shows the origin / cloudflare / ssl split of responsibility
  • Retryable codes carry a Retry-After header; 525 and 526 do not
  • Format is negotiated via the Accept header, live for all zones on all plans

If you build automatic retries, or you're a devops person hitting external APIs through Cloudflare from agents or scripts, this one's for you!

Related posts