Error responses

When Cloudflare cannot complete a request, it generates an error response. The format depends on what the client requests via the Accept header and on the zone's Custom Errors configuration.

By default, error responses are HTML. Clients that request a structured format (such as application/json, application/problem+json, or text/markdown) receive a machine-readable response instead. This machine-readable response covers all 1xxx error codes (which return HTTP 4xx or 5xx status codes depending on the error) and Cloudflare-generated 5xx errors (500, 502, 504, 520-526). Responses for 5xx errors generated by the origin server are passed through by Cloudflare to the client and are not affected.

Cloudflare selects the response format based on the client's Accept header, following standard HTTP content negotiation ↗. When multiple formats are acceptable, quality factors (q values) determine precedence. At the same quality value, the first-listed type wins.

Structured error responses are available on all plans, including the Free plan. Custom Error Rules for overriding these responses require a Cloudflare paid plan.

Structured error responses are the default for zones with no custom error configuration. Zones that use Custom Errors retain full control over what clients receive.

What a client receives depends on which custom error features your zone has configured. Refer to the following sections for details.

This is the default for most zones. Cloudflare serves its default error response in the format the client requests.

The zone has an Error Page uploaded via the Cloudflare dashboard. No Custom Error Rules are configured. The Error Page is served to all clients regardless of Accept header — Error Pages do not perform content negotiation.

If you want agents to receive structured responses while keeping your custom HTML for browsers, add a Custom Error Rule that matches on the Accept header. Refer to the next section for details.

The zone has one or more Custom Error Rules (available on paid plans). These take priority over Error Pages. You control what gets served, to whom, and under what conditions.

Custom Error Rules can match on any request header including Accept, and can target specific error codes. You can serve JSON to API clients, Markdown to agents, and HTML to browsers, all from the same zone.

When Cloudflare generates an error response, the following priority order determines what the client receives:

1. Custom Error Rules — If a rule matches the error and request conditions, the rule's content is served.
2. Error Pages — If an Error Page is configured for the error type and no Custom Error Rule matched, the Error Page is served as HTML regardless of the Accept header.
3. Structured error responses — If no Custom Error Rule matched and no Error Page is configured, Cloudflare serves its default response in the format the client requested (JSON, Markdown, or HTML).

For the full priority order including account-level versus zone-level rules, WAF custom block responses, and security challenge pages, refer to the Custom Errors documentation.

{
	"type": "https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-522/",
	"title": "Error 522: Connection timed out",
	"status": 522,
	"detail": "Cloudflare could not establish a TCP connection to the origin server. The TCP handshake timed out, which may indicate the origin is overloaded, firewalling Cloudflare, or unreachable at the network level.",
	"instance": "9f140b785e57c458",
	"error_code": 522,
	"error_name": "connection_timeout",
	"error_category": "origin",
	"ray_id": "9f140b785e57c458",
	"timestamp": "2026-04-24T09:22:40Z",
	"zone": "example.com",
	"cloudflare_error": true,
	"retryable": true,
	"retry_after": 120,
	"owner_action_required": true,
	"what_you_should_do": "**Wait and retry.** Back off for at least 120 seconds. If the error persists, the website operator should verify firewall rules and ensure the origin accepts connections from Cloudflare IP ranges.",
	"footer": "This error was generated by Cloudflare on behalf of the website owner."
}

---
error_code: 522
error_name: connection_timeout
error_category: origin
status: 522
ray_id: 9f140b785e57c458
timestamp: 2026-04-24T09:22:40Z
zone: example.com
cloudflare_error: true
retryable: true
retry_after: 120
owner_action_required: true
---

# Error 522: Connection timed out

## What Happened

Cloudflare could not establish a TCP connection to the origin server. The TCP handshake timed out, which may indicate the origin is overloaded, firewalling Cloudflare, or unreachable at the network level.

## What You Should Do

**Wait and retry.** Back off for at least 120 seconds. If the error persists, the website operator should verify firewall rules and ensure the origin accepts connections from Cloudflare IP ranges.

---

This error was generated by Cloudflare on behalf of the website owner.

Fetch the structured JSON response for a 522 error:

curl --silent --compressed --header "Accept: application/json" \
  --user-agent "TestAgent/1.0" --header "Accept-Encoding: gzip, deflate" \
  "https://example.com/cdn-cgi/error/522" | jq .

Fetch the structured Markdown response:

curl --silent --compressed --header "Accept: text/markdown" \
  --user-agent "TestAgent/1.0" --header "Accept-Encoding: gzip, deflate" \
  "https://example.com/cdn-cgi/error/522"

Check for the Retry-After header on a retryable error:

curl --silent --compressed --dump-header - --output /dev/null \
  --header "Accept: application/json" --user-agent "TestAgent/1.0" \
  --header "Accept-Encoding: gzip, deflate" \
  "https://example.com/cdn-cgi/error/521" | grep -i retry-after

Both JSON and Markdown responses contain the same set of fields. JSON responses return them as a flat object; Markdown responses place them in YAML frontmatter followed by prose sections. The field definitions below apply to both formats.

JSON responses follow RFC 9457 (Problem Details for HTTP APIs) ↗. Any HTTP client that understands Problem Details can parse the five standard members (type, title, status, detail, instance) without Cloudflare-specific code.

Markdown responses place these fields in YAML frontmatter (between --- delimiters), followed by three prose sections:

• # Error {code}: {description} — heading with the error code and short description.
• ## What Happened — corresponds to the detail field.
• ## What You Should Do — corresponds to the what_you_should_do field.

The frontmatter omits the RFC 9457 standard members (type, title, instance) and the footer field since these are either redundant with the prose or not applicable to the Markdown format.

The error_category field classifies the fault so that clients can route retry and escalation behavior without parsing the prose fields.

Retryable error codes include a standard Retry-After ↗ HTTP response header. The header value in seconds matches the retry_after field in the response body.

Non-retryable codes (525, 526) do not include the Retry-After header.

Six retryable 1xxx error codes emit Retry-After:

All other 1xxx error codes are non-retryable and do not include the Retry-After header.

If a WAF rate limiting rule has already set a dynamic Retry-After value on the response, that value takes precedence over the default.

• Cloudflare 1xxx errors
• Cloudflare 5xx errors
• Custom Errors
• Connection limits
• Markdown for Agents (content conversion)
• RFC 9457 — Problem Details for HTTP APIs ↗