错误响应

当 Cloudflare 无法完成请求时，会生成错误响应。格式取决于客户端通过 Accept 头请求的内容，以及 zone 的 Custom Errors 配置。

默认情况下，错误响应为 HTML。请求结构化格式（例如 application/json、application/problem+json 或 text/markdown）的客户端将收到机器可读响应。此机器可读响应涵盖所有 1xxx 错误代码（根据错误返回 HTTP 4xx 或 5xx 状态码）以及 Cloudflare 生成的 5xx 错误（500、502、504、520-526）。由源站服务器生成的 5xx 错误响应会由 Cloudflare 透传给客户端，不受影响。

内容协商

Cloudflare 根据客户端的 Accept 头选择响应格式，遵循标准 HTTP 内容协商 ↗。当多种格式均可接受时，质量因子（q 值）决定优先级。在相同质量值下，先列出的类型优先。

发送的 `Accept` 头	响应格式
`application/json`	JSON (`application/json; charset=utf-8`)
`application/problem+json`	JSON (`application/problem+json; charset=utf-8`)
`application/json, text/markdown;q=0.9`	JSON（更高质量因子）
`text/markdown`	Markdown (`text/markdown; charset=utf-8`)
`text/markdown, application/json`	Markdown（质量相等时，先列出的优先）
`text/*`	Markdown
`text/html`	HTML
`/`	HTML
未设置	HTML

结构化错误响应适用于所有套餐，包括 Free 套餐。用于覆盖这些响应的 Custom Error Rules 需要 Cloudflare 付费套餐。

与 Custom Errors 的交互

结构化错误响应是未配置自定义错误的 zone 的默认行为。使用 Custom Errors 的 zone 可完全控制客户端收到的内容。

客户端收到的内容取决于 zone 配置了哪些自定义错误功能。详情请参阅以下各节。

无自定义错误页面，无自定义错误规则

这是大多数 zone 的默认情况。Cloudflare 以客户端请求的格式提供默认错误响应。

客户端发送	响应
`Accept: application/json`	默认 Cloudflare 结构化 JSON 响应
`Accept: text/markdown`	默认 Cloudflare 结构化 Markdown 响应
`Accept: text/html`	默认 Cloudflare HTML 错误页面
无 `Accept` 头	默认 Cloudflare HTML 错误页面

已配置 Error Page，无自定义错误规则

zone 通过 Cloudflare 仪表板上传了 Error Page。未配置 Custom Error Rules。无论 Accept 头如何，都会向所有客户端提供 Error Page——Error Pages 不执行内容协商。

客户端发送	响应
`Accept: application/json`	您的自定义 HTML 错误页面
`Accept: text/markdown`	您的自定义 HTML 错误页面
`Accept: text/html`	您的自定义 HTML 错误页面
无 `Accept` 头	您的自定义 HTML 错误页面

如果您希望代理收到结构化响应，同时为浏览器保留自定义 HTML，请添加匹配 Accept 头的 Custom Error Rule。详情请参阅下一节。

已配置 Custom Error Rules

zone 有一个或多个 Custom Error Rules（适用于付费套餐）。这些规则优先于 Error Pages。您可以控制向谁、在什么条件下提供什么内容。

客户端发送	响应
`Accept: application/json`	如果 Custom Error Rule 匹配，则提供规则内容。如果没有规则匹配，则回退到 Error Page（如已配置）或结构化 JSON 响应。
`Accept: text/markdown`	如果 Custom Error Rule 匹配，则提供规则内容。如果没有规则匹配，则回退到 Error Page（如已配置）或结构化 Markdown 响应。
`Accept: text/html`	如果 Custom Error Rule 匹配，则提供规则内容。如果没有规则匹配，则回退到 Error Page 或默认 HTML。
无 `Accept` 头	相同的回退链

Custom Error Rules 可以匹配包括 Accept 在内的任何请求头，并可针对特定错误代码。您可以从同一 zone 向 API 客户端提供 JSON、向代理提供 Markdown、向浏览器提供 HTML。

示例：在 522 错误时向 API 客户端提供自定义 JSON

此 Custom Error Rule 匹配客户端请求 JSON 的 522 错误：

Expression: (http.response.code eq 522) and (any(http.request.headers["accept"][*] contains "application/json"))

Action: 使用您自己的错误格式提供自定义 JSON 响应。

此规则优先于默认结构化 JSON 响应和任何已配置的 Error Page。不匹配该规则的客户端（例如请求 HTML 的浏览器）会回退到 Error Page 或默认 Cloudflare 响应。

示例：向代理提供结构化响应，向浏览器提供自定义 HTML 页面

如果您的 zone 配置了 Error Page，它会提供给所有客户端，包括请求 JSON 或 Markdown 的代理。要让代理改为接收 Cloudflare 的默认结构化响应，请移除 Error Page。没有 Error Page 时，Cloudflare 会自动遵循 Accept 头：代理获得结构化 JSON 或 Markdown，浏览器获得 HTML。

如果您需要为浏览器保留 Error Page，但希望向代理提供自定义结构化内容，请创建匹配 Accept 头并提供您自己的 JSON 或 Markdown 内容的 Custom Error Rules。不匹配任一规则的浏览器将继续接收您的自定义 HTML Error Page。

优先级顺序

当 Cloudflare 生成错误响应时，以下优先级顺序决定客户端收到的内容：

Custom Error Rules — 如果规则匹配错误和请求条件，则提供规则内容。
Error Pages — 如果为错误类型配置了 Error Page 且没有 Custom Error Rule 匹配，则无论 Accept 头如何，都以 HTML 提供 Error Page。
结构化错误响应 — 如果没有 Custom Error Rule 匹配且未配置 Error Page，Cloudflare 以客户端请求的格式（JSON、Markdown 或 HTML）提供默认响应。

有关包括账户级与 zone 级规则、WAF 自定义阻止响应和安全质询页面在内的完整优先级顺序，请参阅 Custom Errors 文档。

示例

JSON: 522 Connection timed out

{
	"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."
}

Markdown: 522 Connection timed out

---
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.

## 你应采取的措施

**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.

测试结构化错误响应

获取 522 错误的结构化 JSON 响应：

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 .

获取结构化 Markdown 响应：

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

检查可重试错误上的 Retry-After 头：

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

响应字段

JSON 和 Markdown 响应包含相同的字段集。JSON 响应将它们作为扁平对象返回；Markdown 响应将它们放在 YAML frontmatter 中，后跟正文部分。以下字段定义适用于两种格式。

JSON 响应遵循 RFC 9457 (Problem Details for HTTP APIs) ↗。任何理解 Problem Details 的 HTTP 客户端都可以解析五个标准成员（type、title、status、detail、instance），无需 Cloudflare 特定代码。

RFC 9457 标准成员

字段	类型	说明
`type`	string	指向此错误代码的 Cloudflare 文档的 URI。
`title`	string	简短摘要，例如 `"Error 522: Connection timed out"`。
`status`	integer	响应的 HTTP 状态码。
`detail`	string	对出错原因及责任方的纯文本说明。
`instance`	string	标识此特定错误发生的 Ray ID。

Cloudflare 扩展成员

字段	类型	说明
`error_code`	integer	Cloudflare 错误代码（例如 `522`、`1015`）。
`error_name`	string	`snake_case` 机器可读名称（例如 `connection_timeout`、`rate_limited`）。稳定——适合程序化匹配。
`error_category`	string	故障分类。请参阅错误类别。稳定——适合程序化匹配。
`ray_id`	string	与 `instance` 相同的值。为与现有 Cloudflare 工具兼容而包含。
`timestamp`	string	错误生成时的 ISO 8601 时间戳。
`zone`	string	请求的主机名。
`cloudflare_error`	boolean	始终为 `true`。确认此错误由 Cloudflare 生成，而非源站。
`retryable`	boolean	错误是否为瞬时且请求可重试。
`retry_after`	integer or null	重试前等待的秒数。仅当 `retryable` 为 `true` 时存在。与 `Retry-After` HTTP 头值匹配。
`owner_action_required`	boolean	站点运营商是否需要采取措施解决错误。
`what_you_should_do`	string	面向客户端的可操作指导：下一步做什么、是否重试，以及谁可以修复问题。
`footer`	string	归属行。

Markdown 特定结构

Markdown 响应将这些字段放在 YAML frontmatter 中（在 --- 分隔符之间），后跟三个正文部分：

# Error {code}: {description} — 带有错误代码和简短描述的标题。
## What Happened — 对应 detail 字段。
## 你应采取的措施 — 对应 what_you_should_do 字段。

Frontmatter 省略了 RFC 9457 标准成员（type、title、instance）和 footer 字段，因为这些与正文重复或不适用于 Markdown 格式。

错误类别

error_category 字段对故障进行分类，以便客户端无需解析正文字段即可路由重试和升级行为。

5xx 错误类别

类别	代码	含义	是否重试？
`origin`	502, 504, 520-524	源站服务器负责。瞬时基础设施故障。	是。使用 `retry_after` 退避。
`cloudflare`	500	Cloudflare 遇到内部错误。源站不一定参与。	是。短暂重试（30 秒）。
`ssl`	525, 526	源站的 TLS 配置已损坏（握手失败或证书无效）。	否。在运营商修复 TLS 配置之前，重试无济于事。

1xxx 错误类别

类别	含义	示例代码
`access_denied`	IP 阻止、国家/地区阻止、防火墙规则	1005, 1006, 1007, 1008, 1010, 1012, 1106-1109
`rate_limit`	速率限制	1015, 1025, 1027, 1200
`dns`	DNS 解析错误	1001, 1016
`config`	Zone 或源站配置错误	1004, 1014, 1033, 1043, 1047, 1049
`tls`	客户端 TLS 错误（版本、密码套件、证书）	1017, 1028, 1029, 1044
`legal`	法律限制（DMCA、国家/地区阻止）	1026, 1039
`worker`	Worker 脚本错误	1042, 1100, 1101, 1102, 1103, 1104, 1105
`rewrite`	URL 重写规则错误	1036, 1037
`snippet`	Snippet 配置错误	1201, 1202, 1203, 1204, 1205, 1206
`unsupported`	不支持的功能或协议	1045

Retry-After 头

可重试的错误代码包含标准 Retry-After ↗ HTTP 响应头。头中的秒数值与响应正文中的 retry_after 字段匹配。

5xx Retry-After 值

代码	`retry_after`（秒）
500	30
502	60
504	120
520	60
521	120
522	120
523	120
524	120
525	不适用（不可重试）
526	不适用（不可重试）

不可重试的代码（525、526）不包含 Retry-After 头。

1xxx Retry-After 值

六个可重试的 1xxx 错误代码会发出 Retry-After：

代码	`retry_after`（秒）	错误名称
1004	120	DNS 解析错误
1015	30	速率受限
1033	120	Argo Tunnel 错误
1038	60	HTTP 标头超出限制
1200	60	缓存连接限制
1205	5	重定向过多

所有其他 1xxx 错误代码不可重试，不包含 Retry-After 头。

如果 WAF 速率限制规则已在响应上设置了动态 Retry-After 值，则该值优先于默认值。