{"id":412,"date":"2026-04-27T00:00:00","date_gmt":"2026-04-27T00:00:00","guid":{"rendered":"https:\/\/wordpress.securinsight.ca\/index.php\/2026\/04\/27\/cloudflare-fundamentals-structured-error-responses-for-cloudflare-5xx-errors\/"},"modified":"2026-04-27T00:00:00","modified_gmt":"2026-04-27T00:00:00","slug":"cloudflare-fundamentals-structured-error-responses-for-cloudflare-5xx-errors","status":"publish","type":"post","link":"https:\/\/wordpress.securinsight.ca\/index.php\/2026\/04\/27\/cloudflare-fundamentals-structured-error-responses-for-cloudflare-5xx-errors\/","title":{"rendered":"Cloudflare Fundamentals &#8211; Structured error responses for Cloudflare 5xx errors"},"content":{"rendered":"<p>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 <a href=\"https:\/\/www.rfc-editor.org\/rfc\/rfc9457\" target=\"_blank\">RFC 9457 (Problem Details for HTTP APIs)<\/a> and include a <code>Retry-After<\/code> HTTP header on retryable codes.<\/p>\n<h4>Changes<\/h4>\n<p><strong>5xx coverage.<\/strong> 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.<\/p>\n<p><strong>Fault attribution.<\/strong> The <code>error_category<\/code> field tells agents where the fault lies:<\/p>\n<ul>\n<li><code>origin<\/code> (502, 504, 520-524) \u2014 the origin server is responsible. Transient; retry with the backoff in <code>retry_after<\/code>.<\/li>\n<li><code>cloudflare<\/code> (500) \u2014 Cloudflare&#8217;s fault, not the website or the request. Short retry.<\/li>\n<li><code>ssl<\/code> (525, 526) \u2014 the origin&#8217;s TLS configuration is broken. Do not retry.<\/li>\n<\/ul>\n<p><strong>Retry-After header.<\/strong> Retryable codes (500, 502, 504, 520-524) include a <code>Retry-After<\/code> HTTP header matching the <code>retry_after<\/code> body field. Non-retryable codes (525, 526) do not include the header.<\/p>\n<h4>Negotiation behavior<\/h4>\n<table>\n<thead>\n<tr>\n<th>Request header sent<\/th>\n<th>Response format<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>Accept: application\/json<\/code><\/td>\n<td>JSON (<code>application\/json<\/code> content type)<\/td>\n<\/tr>\n<tr>\n<td><code>Accept: application\/problem+json<\/code><\/td>\n<td>JSON (<code>application\/problem+json<\/code> content type)<\/td>\n<\/tr>\n<tr>\n<td><code>Accept: application\/json, text\/markdown;q=0.9<\/code><\/td>\n<td>JSON<\/td>\n<\/tr>\n<tr>\n<td><code>Accept: text\/markdown<\/code><\/td>\n<td>Markdown<\/td>\n<\/tr>\n<tr>\n<td><code>Accept: text\/markdown, application\/json<\/code><\/td>\n<td>Markdown (equal <code>q<\/code>, first-listed wins)<\/td>\n<\/tr>\n<tr>\n<td><code>Accept: *\/*<\/code><\/td>\n<td>HTML (default)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h4>Availability<\/h4>\n<p>Available now for all zones on all plans.<\/p>\n<h4>Get started<\/h4>\n<p>Get JSON response for error 522:<\/p>\n<div>\n<figure>\n<pre data-language=\"bash\"><code class=\"language-bash\"><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>\"&lt;YOUR_DOMAIN&gt;\/cdn-cgi\/error\/522\"<\/span><span> <\/span><span>|<\/span><span> <\/span><span>jq<\/span><span> <\/span><span>.<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div>\n<p>Check presence of the <code>Retry-After<\/code> HTTP header associated with the JSON response for error 521:<\/p>\n<div>\n<figure>\n<pre data-language=\"bash\"><code class=\"language-bash\"><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>\"&lt;YOUR_DOMAIN&gt;\/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><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div>\n<p>References:<\/p>\n<ul>\n<li><a href=\"https:\/\/www.rfc-editor.org\/rfc\/rfc9457\" target=\"_blank\">RFC 9457 \u2014 Problem Details for HTTP APIs<\/a><\/li>\n<li><a href=\"https:\/\/developers.cloudflare.com\/support\/troubleshooting\/http-status-codes\/cloudflare-5xx-errors\/\">Cloudflare 5xx error documentation<\/a><\/li>\n<\/ul>","protected":false},"excerpt":{"rendered":"<p>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. [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-412","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/posts\/412","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/comments?post=412"}],"version-history":[{"count":0,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/posts\/412\/revisions"}],"wp:attachment":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/media?parent=412"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/categories?post=412"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/tags?post=412"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}