RemoteHttpError

What this error means and what can trigger it

Copied link.

RemoteHttpError means a remote operation reached a failure with known HTTP semantics. It is a tagged data record, not a JavaScript Error. Its required status identifies the response class; body may preserve a parsed response body, and cause may retain the native failure that supplied the status.

SER reaches this variant through several paths. A remote form error envelope may contain a payload that is not one of SER's tagged failures; a native remote helper may reject with an object exposing a numeric status; or an unsuccessful Response may contain a body that does not decode to an existing tagged failure. In every case, SER knows the HTTP status even though it cannot recover a more specific typed failure.

Exactly where it triggers

Copied link.

An unrecognized form error envelope falls back to its reported status, or 500 when the envelope omitted one:

const decoded_error = decode_remote_error(response.error);

if (is_remote_failure(decoded_error)) {
	throw decoded_error;
}

throw create_remote_http_error(response.status ?? 500, response.error);

A native rejected value with a numeric status is normalized here:

if (status !== undefined) {
	return create_remote_http_error(status, body, error);
}

A failed Response whose body is not already a tagged failure is converted here:

const decoded_error = decode_remote_error(body);

if (is_remote_failure(decoded_error)) {
	return decoded_error;
}

return create_remote_http_error(response.status, body);

The common constructor is modules/svelte-effect-runtime/src/remote/shared.ts L313 @ C17.

Why this is the case

Copied link.

The known status gives callers something concrete to act on. 401, 404, and 503, for example, describe different server outcomes even when their bodies are empty or unfamiliar. Folding all of them into RemoteTransportError would discard information needed for authentication, missing resources, or retry behavior.

SER preserves an existing tagged remote failure before using this fallback. The HTTP wrapper is therefore reserved for failures whose status is meaningful but whose body cannot be assigned a more specific SER tag. Only the native normalization path includes the original thrown object as cause, because that is the path where such an object exists.