528 Transport Errors

Fluxzy returns the HTTP 528 status code whenever it cannot start or complete a request against the upstream server. A transport error covers anything that prevents Fluxzy from producing a real upstream response, including:

DNS resolution failures
TCP connection refusals, resets, or timeouts
TLS handshake or certificate errors
Protocol violations from the remote
Read timeouts or premature connection closes

Instead of dropping the connection to the client, Fluxzy synthesizes a 528 response with a human-readable body that summarizes the diagnosis:

528 Transport Error

Machine-readable diagnosis: `x-fluxzy-network-error` (Fluxzy 1.36+)

Starting with Fluxzy 1.36, every synthesized 528 response also carries a short, stable token in the x-fluxzy-network-error header. This lets tools, test runners, and CI pipelines branch on the exact failure category without parsing the HTML body.

HTTP/1.1 528 Fluxzy error
x-fluxzy: Fluxzy error
x-fluxzy-network-error: tls_cert_expired
Content-Type: text/html; charset=utf-8
Connection: close

<html>...</html>

The same token is persisted on ClientError.NetworkErrorCode in .fxzy and HAR archives, so post-mortem readers can recover it.

The token strings are a public contract: they are exposed as public const string on Fluxzy.Core.NetworkErrorCodes and will not change outside of a major version bump.

Token reference

Connection layer

Token	Meaning
`connection_refused`	The remote actively refused the TCP connection (RST on SYN).
`connection_reset`	The remote reset an established connection.
`connection_aborted`	The connection was aborted, often a half-close without a clean FIN.
`connection_timeout`	The remote could not be contacted within the configured TCP connect timeout.
`host_unreachable`	The OS reports no route to the remote host (ICMP host-unreachable).
`network_unreachable`	The OS reports no route to the remote network.
`connection_closed`	The remote closed the TCP connection while Fluxzy was reading the response header.

DNS layer

Token	Meaning
`dns_notfound`	DNS returned `NXDOMAIN`: the host does not exist.
`dns_no_data`	The name resolved but no usable A/AAAA record was returned.
`dns_try_again`	Transient DNS failure (`SERVFAIL` or equivalent); a retry might succeed.
`dns_failure`	Generic DNS failure: malformed response, unreachable resolver, DoH endpoint returning non-2xx.

TLS layer

Token	Meaning
`tls_cert_expired`	The server certificate is past (or not yet within) its validity period.
`tls_cert_hostname_mismatch`	The certificate is valid but does not cover the requested hostname (Subject / SAN).
`tls_cert_untrusted`	The certificate chain does not chain to a trusted root.
`tls_cert_invalid`	Other certificate-policy failure: revoked, malformed, or required but missing.
`tls_handshake_failure`	TLS handshake failed for a non-certificate reason (alert, version, cipher, ...).

Other

Token	Meaning
`protocol_error`	An HTTP/2 stream protocol error happened before the response header was received.
`rule_failure`	A user-supplied Fluxzy rule (filter or action) threw during exchange processing.
`unknown`	Fallback when none of the categories above match: a wrapped exception with no further detail.

Reading the token

From an HTTP client (C#)

using var response = await httpClient.GetAsync(url);

if ((int)response.StatusCode == 528 &&
    response.Headers.TryGetValues("x-fluxzy-network-error", out var values))
{
    var token = values.Single();
    // Compare against Fluxzy.Core.NetworkErrorCodes.* constants
}

From a Fluxzy archive

foreach (var clientError in exchange.ClientErrors)
{
    var token = clientError.NetworkErrorCode; // null on success
}

Common error messages (response body)

The synthesized body still describes each failure in plain English. The most common cases:

The connection was reset by remote peer `

x-fluxzy-network-error: connection_reset. The remote requested an immediate TCP termination, either during the handshake or amid an active connection. This usually means there is no path-level network issue; the remote chose to hang up.

The remote peer could not be contacted within the configured timeout

x-fluxzy-network-error: connection_timeout. The TCP connect did not complete in time. Common causes:

The remote is not reachable (no route to host).
The remote is reachable but silently drops the SYN (firewall, closed port).
The response is lost on the way back (routing issue).
The path is too slow to complete the handshake within the timeout.

Failed to solve DNS for hostname

x-fluxzy-network-error: dns_notfound, dns_no_data, dns_try_again, or dns_failure. DNS resolution did not yield a usable IP. Causes:

The hostname does not exist (NXDOMAIN).
The resolver is unreachable or did not respond in time.
The resolver returned an error (SERVFAIL) or no A/AAAA record.
The response was malformed.

Use 502 instead of 528

Strictly speaking, an intermediary should return 502 Bad Gateway for an upstream failure. Fluxzy uses 528 by default so that a debugging response is easy to tell apart from a genuine reverse-proxy failure. To switch back to 502:

Fluxzy CLI: pass --use-502 to the start command.
Fluxzy Desktop: Settings → Proxy settings.
Fluxzy Core: set FluxzySharedSetting.Use528 = false.

The x-fluxzy-network-error header is emitted in both modes.

More diagnosis

For deeper diagnosis, set the environment variable EnableDumpStackTraceOn502=TRUE to include the underlying stack trace in the synthesized body.