Errors — TSN response and failure codes - TSN

TSN errors are fail-closed: a route, intent, lease, or upstream provider is not treated as valid when its required evidence is unavailable.

Node HTTP errors

Status	Meaning in the inspected source	Typical trigger
`401` / `403`	Authentication or authorization failure	Missing/invalid worker key or a settlement lease owned by another Cranker.
`404`	Resource does not exist	Unknown intent or TIN operation identifier.
`409`	State conflict	Duplicate authorization, expired lease, wrong lifecycle state, missing finalized route, or a TCap route being sent through the legacy payout path.
`422`	Request or signed payload is invalid	Missing required fields, unsupported token, invalid commitment, or malformed route data.
`503`	Service or route registry is unavailable	Node verifier is not ready or the settlement registry cannot be read safely.

The Node’s FastAPI error body is normally an object with a detail field. The exact detail text is part of the source behavior for each endpoint and should not be parsed as a stable error code.

JSON-RPC gateway errors

The gateway returns JSON-RPC 2.0 error objects for malformed JSON (-32700), invalid JSON-RPC requests (-32600), and upstream failure. HTTP status is 400 for malformed/invalid requests and 502 when all upstream providers fail.

SDK errors

TsnHttpClient throws Error("TSN request failed (<status>): <body>") for a non-2xx response. Validation helpers in payment-authorization.ts, cross-chain.ts, and tins.ts throw ordinary JavaScript Error values with source-defined messages.

Minimal handling example

try {
  await client.postIntent(request);
} catch (error) {
  const message = error instanceof Error ? error.message : String(error);
  console.error(message);
}

TODO: introduce stable machine-readable Node error codes only after the service source defines them. This reference intentionally does not convert current human-readable detail strings into invented codes. Source: server.py:3500-3640, server.py:4009-4108, gateway.mjs:515-579, client.ts:22-62