index/interfaces/FailureView.md

A failure as a PLAIN OBJECT: the facts the SDKs' guards and classifiers (gswap-sdk's classifyFailure) read, and nothing else. A real GalaSDKError is one (every field below is on it, and on every product subclass); so is the wrapper an app makes from an SDK error to carry through its own layers (an app's own failure class or error data), which has a code and params but is not an instanceof anything the SDK owns. gswap-sdk's classifyFailure, isRelayableRefusal, isUnprovenAcknowledgement, isUninterpretedAnswer, isPreSendError, isShadowError, isNoMarket and mayHaveBeenQueued all accept such an object wherever they accept an SDK error, and decide from the SAME fields in the same way, so an app never has to keep the original error just to ask.

Only code is required. A field that is missing, or has the wrong type, reads as absent: a view with no status is not a 404. Nothing here is text: the SDK never reads message of a view.

READ OR WRITE: a view is a WRITE's unless it says it is a read. This fails CLOSED on purpose: a 5xx on a write may have been queued (unknown, no retry) and the same 5xx on a read changed nothing (transient, retry), so a wrapper that drops its uniqueKey must never turn the first into the second. A view is a read ONLY when it states write: false and has no uniqueKey; GalaSDKError.write is already set that way for every SDK read. isWriteView is the one definition.

APP ERRORS: a code the SDK catalog does not define is unknown (the SDK cannot say what happened, and a wrong "failed" invites a duplicate), unless the view declares outcome.

Properties

Property	Modifier	Type	Description
code	readonly	string	The catalog code ('HTTP_ERROR', 'CHAIN_REJECTED', ...). A string the SDK does not know classifies as unknown.
notFound?	readonly	boolean	True for "that thing does not exist" (GalaSDKError.notFound: a market, for gswap-sdk).
outcome?	readonly	"rejected" | "unknown" | "not_queued" | "not_sent" | "invalid_input" | "transient"	What an error the APP raised means, for a code the SDK catalog does not define ('POSITION_STALE', 'AMOUNT_SIDE'): not_sent for a step that failed before anything was signed or sent, and so on. The SDK honours it ONLY for such a code: for a catalog code the SDK's own table decides, so an app cannot declare a refusal the SDK knows to be unknown as safe. A non-catalog code with no outcome stays unknown, and mayHaveBeenQueued is then true.
params?	readonly	Readonly<Record<string, unknown>>	The error's flat params (status of an HTTP_ERROR, reason of a SIGNING_FAILED, ...).
phase?	readonly	"pre_send" | "in_flight" | "post_send"	How far the request got; when absent, the catalog's phase for code.
retryable?	readonly	false	WITHHOLD-ONLY: false takes Retry away from the declared outcome (an app's DID_NOT_QUEUE is { outcome: 'not_queued', retryable: false }, the SDK's NOT_QUEUED_FINAL). Any other value, true included, reads as absent: a view can never GRANT Retry to an outcome that does not have it, and it is read only together with outcome, for a code the catalog does not define.
shadow?	readonly	boolean	True when the failure came from the shadow (dark) path.
status?	readonly	number	The HTTP status of the answer the failure was made from.
uniqueKey?	readonly	string	The uniqueKey of the WRITE this is about; its presence makes the failure a write's.
write?	readonly	boolean	false says the failed call was a READ (no uniqueKey to confirm, nothing pending). Anything else, including absent, is a write: see the note on FailureView. With a uniqueKey the failure is a write whatever this says.