cf-custom-codes
Cloudflare Custom Codes
Cloudflare's error page describes a failed request from Cloudflare's point of view. The origin is the server behind its proxy. A message about that server can also point to a firewall, a routing problem, or a setting in Cloudflare's dashboard.
These are possible explanations for errors 520–526 on proxied websites, followed by a historical note on 527. The code helps narrow the investigation, but usually does not establish the cause by itself.
520: Web server returns an unknown error
Cloudflare received an empty or unexpected response that it could not handle. Possible causes include a crashed application, a malformed HTTP response, response headers over the documented 128 KB limit, or a server that advertises HTTP/2 support but does not handle it correctly. Firewalls blocking Cloudflare can also cause it. Cloudflare's 520 documentation.
The wording can suggest that the web server returned an error code. It may have returned no usable HTTP response at all. A 520 alone does not distinguish an application crash from a protocol or filtering problem.
A useful problem-details body could reduce the guesswork and support back-and-forth here. RFC 9457 section 3.1.4 provides a detail field for an explanation of the particular failure, and section 3.2 allows additional fields that software can read. For example, if the proxy knows the response headers exceeded a limit, saying so gives the operator something concrete to fix. Cloudflare already supports this format, but repeating “unknown error” in JSON would leave the same uncertainty.
521: Web server is down
Cloudflare's connection was refused. The web server might be stopped, but a firewall or other security software might also be rejecting Cloudflare's addresses. The server must be listening on the port Cloudflare is using; for example, changing to Full encryption normally requires HTTPS on port 443. Cloudflare's 521 documentation.
“Down” is broader than the evidence supports. A server can be running and reachable from your laptop while refusing connections from Cloudflare. Check the listener and access rules before treating this as a crashed server.
522: Connection timed out
Cloudflare documents two cases: no SYN+ACK within 19 seconds while opening a TCP connection, or no TCP acknowledgement of its request within 90 seconds after connecting. Blocked or dropped packets, an overloaded server, and an incorrect origin IP address are possible causes. Cloudflare's 522 documentation.
This is not necessarily an application taking too long to generate a page. It concerns TCP connection setup or acknowledgement, which can fail before the application receives the request. An empty application log therefore does not rule out a real failure.
523: Origin is unreachable
Cloudflare cannot reach the origin. Its documentation points to routing problems and recommends checking the origin address in the zone's A and AAAA records. A stale address after a server move is one possible explanation. Cloudflare's 523 documentation.
“Unreachable” means unreachable from Cloudflare along that route. It does not prove the server is offline. Also, DNS resolution failure and a disconnected Tunnel have their own documented errors: 1016 for origin DNS resolution and 1033 when no healthy Tunnel connector is available. Treating all three as 523 can send you to the wrong settings.
524: A timeout occurred
Cloudflare connected to the origin, then reached a timeout while waiting for a response or writing request data. The documented default read timeout is 125 seconds. The write timeout is 30 seconds, with a 6.5-second exception for Cloudflare Images. Enterprise customers can raise the read timeout to as much as 6,000 seconds; the write timeout cannot be raised. Cloudflare's 524 documentation.
A slow query, resource shortage, or long-running job could explain the delay. The error tells you that Cloudflare stopped waiting, not why the request took too long. A request can work when sent directly to the origin yet fail through the proxy because the two clients have different time limits.
525: SSL handshake failed
The TLS handshake between Cloudflare and the origin failed. For ordinary proxied HTTPS requests, this applies to Full and Full (strict) encryption. Possible causes include an origin that is not configured to serve TLS, incompatible cipher suites, or problems handling SNI, the hostname sent during the handshake. Cloudflare's 525 documentation.
With these modes, there are two TLS connections: browser to Cloudflare, and Cloudflare to origin. A working browser connection to Cloudflare does not test the second one. If 525 starts after an encryption-mode change, compare the origin's TLS setup with what Cloudflare now expects.
526: Invalid SSL certificate
Cloudflare could not validate the origin's certificate. For an ordinary proxied website, check Full (strict) requirements: expiry, hostname, trusted issuer, and a complete certificate chain. Cloudflare also documents 526 in Workers and Gateway, where the validation rules can differ from the zone setting. Cloudflare's 526 documentation.
The failed certificate check is on the origin connection, so replacing the certificate shown to browsers may not help. Full (strict) accepts Cloudflare Origin CA certificates as well as publicly trusted ones. Switching to Full removes certificate validation; that can hide the error without fixing the certificate.
527: Railgun error (historical)
527 belonged to Railgun, Cloudflare's retired service for accelerating traffic between its network and origins. Cloudflare's retirement announcement set January 31, 2024 as the last day of support and February 1 as the date existing connections would stop.
Old advice about restarting a Railgun listener describes that retired setup. It is not a general fix for current Cloudflare connection errors.
Reading the error page
A “Host Error” label is a starting point for investigation. It cannot tell you whether the fix belongs in the application, a load balancer, a firewall, DNS, or Cloudflare's connection settings. Record the URL, time and timezone, and Ray ID. Check the logs along the request path, including proxies and firewalls; Cloudflare's troubleshooting guide explicitly notes that the cause may be absent from the origin's error log.
Cloudflare also supports structured error responses, including RFC 9457 JSON requested with Accept: application/problem+json. Custom error pages can override this. A structured response makes the error easier to process, but its category still needs checking against logs and configuration.
Sources and dates
Checked against the linked Cloudflare documentation on September 27, 2026. Timeout and size limits can change; consult the relevant error page and the connection limits reference when investigating a current incident.