diff --git a/core/errors/__tests__/problem-details.contract.test.ts b/core/errors/__tests__/problem-details.contract.test.ts
new file mode 100644
index 0000000..1434281
--- /dev/null
+++ b/core/errors/__tests__/problem-details.contract.test.ts
@@ -0,0 +1,458 @@
+/**
+ * Contract drift tests for the RFC 7807 problem-details taxonomy (#267).
+ *
+ * These tests lock the shape of `ProblemDetails` and the stable code registry.
+ * If a required field is removed, renamed, or changes type, CI will fail here
+ * rather than silently breaking a downstream consumer.
+ *
+ * Rules encoded here:
+ *   1. Every `ProblemDetails` must have the seven required fields.
+ *   2. `code` is always a lowercase_snake string from `PROBLEM_CODES`.
+ *   3. `type` is always an absolute URI starting with `https://utix.dev/problems/`.
+ *   4. `retryable` is always a boolean.
+ *   5. `status` is always a finite number.
+ *   6. No code is ever removed from `PROBLEM_CODES` (enforced by the
+ *      exhaustive membership test against the `ProblemCode` union).
+ *   7. The `HorizonErrorCode → ProblemCode` mapping covers all seven Horizon codes.
+ *   8. The `RpcErrorCode → ProblemCode` mapping covers all eight RPC codes.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  assertContract,
+  contractOperation,
+  validateContract,
+  type ContractSchema
+} from "@/core/contract/contract";
+import {
+  PROBLEM_CODES,
+  problemDetailsFromCode,
+  getProblemDefinition,
+  isProblemRetryable,
+  horizonToProblemDetails,
+  rpcToProblemDetails,
+  type ProblemCode,
+  type ProblemDetails
+} from "@/core/errors/problem-details";
+import { classifyHorizonError } from "@/core/horizon/errors";
+import {
+  classifyRpcError,
+  classifyRpcTransportError
+} from "@/core/rpc/errors";
+import { RPC_STANDARD_CODES, type JsonRpcFailure } from "@/core/rpc/client";
+
+// ─── Locked contract schema ───────────────────────────────────────────────────
+
+const V = "1.0";
+
+/**
+ * The locked `ContractSchema` for a `ProblemDetails` envelope.
+ *
+ * When you add non-breaking optional fields, add them here with `required: false`.
+ * When you add a new *required* field, update this schema AND
+ * `docs/API_CONTRACT.md` in the same commit.
+ */
+const problemDetailsSchema: ContractSchema = {
+  version: V,
+  fields: {
+    type: { type: "string", required: true },
+    title: { type: "string", required: true },
+    status: { type: "number", required: true },
+    detail: { type: "string", required: true },
+    code: { type: "string", required: true },
+    retryable: { type: "boolean", required: true },
+    hint: { type: "string", required: true }
+  }
+};
+
+const problemDetailsContract = contractOperation("problem.details", problemDetailsSchema);
+
+// ─── Canonical codes that must always be present ─────────────────────────────
+
+/**
+ * This list is the *exhaustive* set of `ProblemCode` values that the taxonomy
+ * must contain. If a code is removed from `PROBLEM_CODES`, one of these
+ * assertions will fail — catching an accidental deletion.
+ *
+ * When adding a new code, add it here too.
+ */
+const ALL_PROBLEM_CODES: ProblemCode[] = [
+  // Validation
+  "validation_error",
+  "invalid_address",
+  "invalid_amount",
+  "invalid_asset_code",
+  "missing_required_field",
+  // Stellar account
+  "account_not_found",
+  "account_unfunded",
+  "account_merge_ineligible",
+  // Stellar asset / trustline
+  "asset_not_found",
+  "trustline_missing",
+  "trustline_limit_exceeded",
+  "trustline_no_issuer",
+  // Stellar transaction
+  "transaction_not_found",
+  "transaction_malformed",
+  "transaction_failed",
+  "sequence_mismatch",
+  "insufficient_fee",
+  "precondition_failed",
+  // Soroban
+  "soroban_simulation_failed",
+  "soroban_invocation_failed",
+  "soroban_resource_limit_exceeded",
+  "soroban_contract_not_found",
+  "xdr_decode_error",
+  "xdr_encode_error",
+  // Horizon transport
+  "horizon_not_found",
+  "horizon_rate_limited",
+  "horizon_bad_request",
+  "horizon_server_error",
+  "horizon_network_unavailable",
+  "horizon_timeout",
+  "horizon_unknown",
+  // Soroban RPC transport
+  "rpc_parse_error",
+  "rpc_invalid_request",
+  "rpc_method_not_found",
+  "rpc_invalid_params",
+  "rpc_server_error",
+  "rpc_network_unavailable",
+  "rpc_timeout",
+  "rpc_unknown",
+  // Internal
+  "internal_error"
+];
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("problem-details contract drift tests", () => {
+  describe("ProblemDetails shape", () => {
+    it("locks the ProblemDetails envelope shape for a representative code", () => {
+      const pd: ProblemDetails = problemDetailsFromCode("account_not_found", {
+        correlationId: "test-correlation-id"
+      });
+      expect(assertContract(problemDetailsContract, () => pd).ok).toBe(true);
+    });
+
+    it("locks the shape for a retryable transport code", () => {
+      const pd = problemDetailsFromCode("horizon_rate_limited", {
+        correlationId: "retry-correlation"
+      });
+      expect(assertContract(problemDetailsContract, () => pd).ok).toBe(true);
+      expect(pd.retryable).toBe(true);
+    });
+
+    it("locks the shape for a Soroban code", () => {
+      const pd = problemDetailsFromCode("soroban_simulation_failed");
+      expect(assertContract(problemDetailsContract, () => pd).ok).toBe(true);
+    });
+
+    it("detects a drifted response that drops `code`", () => {
+      const drifted = {
+        type: "https://utix.dev/problems/account-not-found",
+        title: "Account Not Found",
+        status: 404,
+        detail: "No account.",
+        // `code` intentionally omitted
+        retryable: false,
+        hint: "Check the address."
+      };
+      expect(validateContract(drifted, problemDetailsSchema).ok).toBe(false);
+    });
+
+    it("detects a drifted response that drops `hint`", () => {
+      const drifted = {
+        type: "https://utix.dev/problems/account-not-found",
+        title: "Account Not Found",
+        status: 404,
+        detail: "No account.",
+        code: "account_not_found",
+        retryable: false
+        // `hint` intentionally omitted
+      };
+      expect(validateContract(drifted, problemDetailsSchema).ok).toBe(false);
+    });
+
+    it("detects a drifted response where `status` changes type", () => {
+      const drifted = {
+        type: "https://utix.dev/problems/account-not-found",
+        title: "Account Not Found",
+        status: "404", // wrong: should be number
+        detail: "No account.",
+        code: "account_not_found",
+        retryable: false,
+        hint: "Check the address."
+      };
+      expect(validateContract(drifted, problemDetailsSchema).ok).toBe(false);
+    });
+  });
+
+  describe("PROBLEM_CODES registry stability", () => {
+    it("contains every code in the exhaustive code list (no code was removed)", () => {
+      for (const code of ALL_PROBLEM_CODES) {
+        expect(
+          PROBLEM_CODES,
+          `Code "${code}" is missing from PROBLEM_CODES`
+        ).toHaveProperty(code);
+      }
+    });
+
+    it("matches the canonical count — adding codes requires updating ALL_PROBLEM_CODES too", () => {
+      const registryCount = Object.keys(PROBLEM_CODES).length;
+      expect(registryCount).toBe(ALL_PROBLEM_CODES.length);
+    });
+
+    it("has matching keys and code values for every entry", () => {
+      for (const [key, def] of Object.entries(PROBLEM_CODES)) {
+        expect(def.code, `Key "${key}" does not match def.code`).toBe(key);
+      }
+    });
+
+    it("every type URI starts with the stable base URI", () => {
+      for (const [key, def] of Object.entries(PROBLEM_CODES)) {
+        expect(
+          def.type,
+          `Code "${key}" has an unexpected type URI`
+        ).toMatch(/^https:\/\/utix\.dev\/problems\//);
+      }
+    });
+
+    it("every status is a finite integer HTTP status code", () => {
+      for (const [key, def] of Object.entries(PROBLEM_CODES)) {
+        expect(
+          Number.isFinite(def.status) && def.status >= 400 && def.status < 600,
+          `Code "${key}" has an invalid status: ${def.status}`
+        ).toBe(true);
+      }
+    });
+
+    it("every code produces a valid ProblemDetails envelope", () => {
+      for (const code of ALL_PROBLEM_CODES) {
+        const pd = problemDetailsFromCode(code);
+        expect(
+          assertContract(problemDetailsContract, () => pd).ok,
+          `Code "${code}" did not produce a valid ProblemDetails envelope`
+        ).toBe(true);
+      }
+    });
+  });
+
+  describe("getProblemDefinition and isProblemRetryable helpers", () => {
+    it("getProblemDefinition returns the correct entry", () => {
+      const def = getProblemDefinition("invalid_address");
+      expect(def.code).toBe("invalid_address");
+      expect(def.status).toBe(400);
+      expect(def.retryable).toBe(false);
+    });
+
+    it("isProblemRetryable reflects the taxonomy", () => {
+      expect(isProblemRetryable("horizon_rate_limited")).toBe(true);
+      expect(isProblemRetryable("invalid_address")).toBe(false);
+      expect(isProblemRetryable("rpc_timeout")).toBe(true);
+      expect(isProblemRetryable("account_not_found")).toBe(false);
+    });
+  });
+
+  describe("problemDetailsFromCode", () => {
+    it("accepts an overrideDetail without echoing user input", () => {
+      const pd = problemDetailsFromCode("validation_error", {
+        overrideDetail: "The amount field is out of range."
+      });
+      expect(pd.detail).toBe("The amount field is out of range.");
+      // The override must still be a string, not a user-input fragment
+      expect(typeof pd.detail).toBe("string");
+    });
+
+    it("carries the correlationId through", () => {
+      const pd = problemDetailsFromCode("internal_error", { correlationId: "cid-123" });
+      expect(pd.correlationId).toBe("cid-123");
+    });
+
+    it("optional fields are absent when not provided", () => {
+      const pd = problemDetailsFromCode("account_not_found");
+      expect(pd.correlationId).toBeUndefined();
+      expect(pd.instance).toBeUndefined();
+      expect(pd.extensions).toBeUndefined();
+    });
+
+    it("optional instance and extensions are preserved", () => {
+      const pd = problemDetailsFromCode("account_not_found", {
+        instance: "/tools/balance-viewer?address=G123",
+        extensions: { network: "testnet" }
+      });
+      expect(pd.instance).toBe("/tools/balance-viewer?address=G123");
+      expect(pd.extensions).toEqual({ network: "testnet" });
+    });
+  });
+
+  describe("Horizon bridge adapter", () => {
+    it("maps every Horizon error code to a ProblemDetails envelope", () => {
+      const horizonCodes = [
+        { response: { status: 404 } },
+        { response: { status: 429 } },
+        { response: { status: 400 } },
+        { response: { status: 500 } },
+        new Error("fetch failed"),
+        new Error("timeout"),
+        new Error("aborted")
+      ] as const;
+
+      for (const raw of horizonCodes) {
+        const classified = classifyHorizonError(raw);
+        const pd = horizonToProblemDetails(classified);
+        expect(
+          assertContract(problemDetailsContract, () => pd).ok,
+          `Horizon code "${classified.code}" did not produce a valid envelope`
+        ).toBe(true);
+      }
+    });
+
+    it("preserves the correlationId from the Horizon classification", () => {
+      const classified = classifyHorizonError({ response: { status: 429 } });
+      const pd = horizonToProblemDetails(classified);
+      expect(pd.correlationId).toBe(classified.correlationId);
+      expect(typeof pd.correlationId).toBe("string");
+    });
+
+    it("does NOT echo raw Horizon error strings in the detail field", () => {
+      // Use a plain error (no response.data) to avoid the pre-existing
+      // `redact` reference bug in core/horizon/errors.ts when response.data
+      // is present. The invariant being tested is that horizonToProblemDetails
+      // never forwards raw server text — it always uses the taxonomy safe message.
+      const classified = classifyHorizonError({ response: { status: 400 } });
+      // Manually attach a detail to simulate what classifyHorizonError produces
+      // when Horizon returns verbose error text.
+      const classifiedWithRaw: typeof classified = {
+        ...classified,
+        detail: {
+          status: 400,
+          title: "user-input-danger",
+          detail: "raw Horizon message with <script>xss</script>"
+        }
+      };
+      const pd = horizonToProblemDetails(classifiedWithRaw);
+      // The raw Horizon detail must NOT appear in the envelope
+      expect(pd.detail).not.toContain("<script>");
+      expect(pd.detail).not.toContain("user-input-danger");
+      expect(pd.detail).not.toContain("raw Horizon message");
+    });
+
+    it("maps a not_found classification to horizon_not_found", () => {
+      const classified = classifyHorizonError({ response: { status: 404 } });
+      const pd = horizonToProblemDetails(classified);
+      expect(pd.code).toBe("horizon_not_found");
+      expect(pd.status).toBe(404);
+    });
+
+    it("maps a rate_limited classification to horizon_rate_limited with retryable=true", () => {
+      const classified = classifyHorizonError({ response: { status: 429 } });
+      const pd = horizonToProblemDetails(classified);
+      expect(pd.code).toBe("horizon_rate_limited");
+      expect(pd.retryable).toBe(true);
+    });
+  });
+
+  describe("Soroban RPC bridge adapter", () => {
+    function makeRpcFailure(code: number): JsonRpcFailure {
+      return {
+        jsonrpc: "2.0",
+        id: 1,
+        error: { code, message: "raw-rpc-message-must-not-appear-in-output" }
+      };
+    }
+
+    it("classifyRpcError maps PARSE_ERROR to rpc_parse_error", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.PARSE_ERROR));
+      expect(classified.code).toBe("rpc_parse_error");
+      const pd = rpcToProblemDetails(classified);
+      expect(assertContract(problemDetailsContract, () => pd).ok).toBe(true);
+    });
+
+    it("classifyRpcError maps INVALID_REQUEST to rpc_invalid_request", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.INVALID_REQUEST));
+      expect(classified.code).toBe("rpc_invalid_request");
+    });
+
+    it("classifyRpcError maps METHOD_NOT_FOUND to rpc_method_not_found", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.METHOD_NOT_FOUND));
+      expect(classified.code).toBe("rpc_method_not_found");
+    });
+
+    it("classifyRpcError maps INVALID_PARAMS to rpc_invalid_params", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.INVALID_PARAMS));
+      expect(classified.code).toBe("rpc_invalid_params");
+    });
+
+    it("classifyRpcError maps INTERNAL_ERROR to rpc_server_error with retryable=true", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.INTERNAL_ERROR));
+      expect(classified.code).toBe("rpc_server_error");
+      expect(classified.retryable).toBe(true);
+    });
+
+    it("classifyRpcError maps MALFORMED_ENVELOPE to rpc_invalid_request", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.MALFORMED_ENVELOPE));
+      expect(classified.code).toBe("rpc_invalid_request");
+    });
+
+    it("classifyRpcError maps HTTP 5xx to rpc_server_error", () => {
+      const classified = classifyRpcError(makeRpcFailure(503));
+      expect(classified.code).toBe("rpc_server_error");
+    });
+
+    it("classifyRpcError maps unknown codes to rpc_unknown", () => {
+      const classified = classifyRpcError(makeRpcFailure(9999));
+      expect(classified.code).toBe("rpc_unknown");
+    });
+
+    it("classifyRpcTransportError maps AbortError to rpc_timeout with retryable=true", () => {
+      const abort = Object.assign(new Error("aborted"), { name: "AbortError" });
+      const classified = classifyRpcTransportError(abort);
+      expect(classified.code).toBe("rpc_timeout");
+      expect(classified.retryable).toBe(true);
+    });
+
+    it("classifyRpcTransportError maps fetch TypeError to rpc_network_unavailable", () => {
+      const fetchErr = new TypeError("Failed to fetch");
+      const classified = classifyRpcTransportError(fetchErr);
+      expect(classified.code).toBe("rpc_network_unavailable");
+      expect(classified.retryable).toBe(true);
+    });
+
+    it("does NOT echo raw RPC error messages in the safeMessage", () => {
+      const failure = makeRpcFailure(RPC_STANDARD_CODES.INTERNAL_ERROR);
+      const classified = classifyRpcError(failure);
+      expect(classified.safeMessage).not.toContain("raw-rpc-message-must-not-appear-in-output");
+    });
+
+    it("produces a valid ProblemDetails envelope for every RPC standard code", () => {
+      const stdCodes = [
+        RPC_STANDARD_CODES.PARSE_ERROR,
+        RPC_STANDARD_CODES.INVALID_REQUEST,
+        RPC_STANDARD_CODES.METHOD_NOT_FOUND,
+        RPC_STANDARD_CODES.INVALID_PARAMS,
+        RPC_STANDARD_CODES.INTERNAL_ERROR,
+        RPC_STANDARD_CODES.MALFORMED_ENVELOPE
+      ];
+
+      for (const rawCode of stdCodes) {
+        const classified = classifyRpcError(makeRpcFailure(rawCode));
+        const pd = rpcToProblemDetails(classified);
+        expect(
+          assertContract(problemDetailsContract, () => pd).ok,
+          `RPC code ${rawCode} did not produce a valid envelope`
+        ).toBe(true);
+      }
+    });
+
+    it("carries a correlationId through from the RPC classification", () => {
+      const classified = classifyRpcError(makeRpcFailure(RPC_STANDARD_CODES.INTERNAL_ERROR));
+      const pd = rpcToProblemDetails(classified);
+      expect(typeof pd.correlationId).toBe("string");
+      expect(pd.correlationId!.length).toBeGreaterThan(0);
+    });
+  });
+});
diff --git a/core/errors/problem-details.ts b/core/errors/problem-details.ts
new file mode 100644
index 0000000..f884b2c
--- /dev/null
+++ b/core/errors/problem-details.ts
@@ -0,0 +1,631 @@
+/**
+ * RFC 7807 Problem Details taxonomy for Utix (#267).
+ *
+ * This module provides:
+ *   1. `PROBLEM_CODES` — the stable machine-readable code registry. Never rename
+ *      or remove a code; only add new ones. Consumers switch on codes, not on
+ *      English strings.
+ *   2. `ProblemDetails` — the RFC 7807-aligned response shape: `type`, `title`,
+ *      `status`, `detail`, `instance?`, `correlationId`, `code`, `retryable`,
+ *      `hint`, `extensions?`.
+ *   3. `toProblemDetails()` — lifts a `HorizonErrorClassification` or a
+ *      `RpcErrorClassification` into a `ProblemDetails` envelope.
+ *   4. `problemDetailsFromCode()` — creates a `ProblemDetails` from a bare
+ *      `ProblemCode`, taking an optional override for the `detail` field.
+ *
+ * Safe-message invariants
+ * ───────────────────────
+ * - No function here echoes user-supplied input.
+ * - No raw Horizon or RPC error strings are forwarded to consumers.
+ * - The `detail` field is always derived from the internal taxonomy, never from
+ *   an untrusted source.
+ *
+ * Stability contract
+ * ──────────────────
+ * Once a code ships in `PROBLEM_CODES` it is permanent. To evolve meaning,
+ * add a new code and document the old one as "superseded by <new-code>".
+ */
+
+// ─── RFC 7807 base type ───────────────────────────────────────────────────────
+
+/**
+ * A structured error response following RFC 7807 Problem Details for HTTP APIs.
+ *
+ * Extensions beyond RFC 7807:
+ *   `code`      — stable machine-readable identifier (always lowercase_snake)
+ *   `retryable` — whether repeating the request is safe
+ *   `hint`      — actionable remediation hint aimed at the developer
+ *   `correlationId` — passed through from the originating transport layer
+ *   `extensions`    — open-ended map for future non-breaking additions
+ */
+export interface ProblemDetails {
+  /** Absolute URI identifying the problem type (RFC 7807 §3.1). */
+  type: string;
+  /** Short, human-readable summary of the problem. */
+  title: string;
+  /** HTTP status code. */
+  status: number;
+  /** Human-readable, specific explanation of *this* occurrence. */
+  detail: string;
+  /** URI reference to the specific resource that caused the problem. */
+  instance?: string;
+  /** Stable machine-readable code that consumers switch on. */
+  code: ProblemCode;
+  /** Whether the caller can safely retry the request. */
+  retryable: boolean;
+  /** Actionable remediation hint for developers and support staff. */
+  hint: string;
+  /** Passed through from the originating transport layer. */
+  correlationId?: string;
+  /** Non-breaking extension fields for future additions. */
+  extensions?: Record<string, unknown>;
+}
+
+// ─── Stable code registry ─────────────────────────────────────────────────────
+
+/**
+ * Internal definition backing each entry in `PROBLEM_CODES`.
+ */
+export interface ProblemDefinition {
+  /** Lowercase snake-case stable identifier. Never rename once shipped. */
+  readonly code: ProblemCode;
+  /** Absolute URI type reference (RFC 7807 §3.1). */
+  readonly type: string;
+  /** Short summary line. */
+  readonly title: string;
+  /** HTTP status code for the wire response. */
+  readonly status: number;
+  /** Safe default detail string. Never includes user input or raw API errors. */
+  readonly detail: string;
+  /** Whether repeating the request is safe. */
+  readonly retryable: boolean;
+  /** Actionable remediation hint for developers. */
+  readonly hint: string;
+}
+
+/**
+ * Base URI for all Utix problem type URIs.
+ * Consumers compare the full `type` string; the base is an implementation detail.
+ */
+const BASE_URI = "https://utix.dev/problems";
+
+function uri(slug: string): string {
+  return `${BASE_URI}/${slug}`;
+}
+
+// ─── Stable code literal union ────────────────────────────────────────────────
+
+export type ProblemCode =
+  // Validation
+  | "validation_error"
+  | "invalid_address"
+  | "invalid_amount"
+  | "invalid_asset_code"
+  | "missing_required_field"
+  // Stellar account
+  | "account_not_found"
+  | "account_unfunded"
+  | "account_merge_ineligible"
+  // Stellar asset / trustline
+  | "asset_not_found"
+  | "trustline_missing"
+  | "trustline_limit_exceeded"
+  | "trustline_no_issuer"
+  // Stellar transaction
+  | "transaction_not_found"
+  | "transaction_malformed"
+  | "transaction_failed"
+  | "sequence_mismatch"
+  | "insufficient_fee"
+  | "precondition_failed"
+  // Soroban / smart-contract
+  | "soroban_simulation_failed"
+  | "soroban_invocation_failed"
+  | "soroban_resource_limit_exceeded"
+  | "soroban_contract_not_found"
+  | "xdr_decode_error"
+  | "xdr_encode_error"
+  // Horizon transport
+  | "horizon_not_found"
+  | "horizon_rate_limited"
+  | "horizon_bad_request"
+  | "horizon_server_error"
+  | "horizon_network_unavailable"
+  | "horizon_timeout"
+  | "horizon_unknown"
+  // Soroban RPC transport
+  | "rpc_parse_error"
+  | "rpc_invalid_request"
+  | "rpc_method_not_found"
+  | "rpc_invalid_params"
+  | "rpc_server_error"
+  | "rpc_network_unavailable"
+  | "rpc_timeout"
+  | "rpc_unknown"
+  // Internal / unclassified
+  | "internal_error";
+
+// ─── PROBLEM_CODES registry ───────────────────────────────────────────────────
+
+/**
+ * Stable taxonomy of every problem code Utix may surface.
+ *
+ * Rules (strictly enforced by contract drift tests):
+ *   1. Keys and `code` values are identical and must match `ProblemCode`.
+ *   2. No code is ever removed; add a new one to supersede an old one.
+ *   3. Codes are lowercase_snake; do NOT use UPPER_SNAKE here (the UPPER_SNAKE
+ *      codes in `error-codes.ts` are an older, internal-only taxonomy).
+ */
+export const PROBLEM_CODES = {
+  // ── Validation (400) ──────────────────────────────────────────────────────
+  validation_error: {
+    code: "validation_error",
+    type: uri("validation-error"),
+    title: "Validation Error",
+    status: 400,
+    detail: "One or more input values did not pass validation.",
+    retryable: false,
+    hint: "Check the field descriptions and correct the offending values before retrying."
+  },
+  invalid_address: {
+    code: "invalid_address",
+    type: uri("invalid-address"),
+    title: "Invalid Stellar Address",
+    status: 400,
+    detail: "The supplied Stellar address is not a valid public key.",
+    retryable: false,
+    hint: "A Stellar public key starts with 'G' and is exactly 56 Base32 characters. Verify the address and try again."
+  },
+  invalid_amount: {
+    code: "invalid_amount",
+    type: uri("invalid-amount"),
+    title: "Invalid Amount",
+    status: 400,
+    detail: "The amount is not a valid Stellar quantity.",
+    retryable: false,
+    hint: "Amounts must be positive, use at most 7 decimal places, and fit within Stellar's 64-bit fixed-point range (≤ 922,337,203,685.4775807)."
+  },
+  invalid_asset_code: {
+    code: "invalid_asset_code",
+    type: uri("invalid-asset-code"),
+    title: "Invalid Asset Code",
+    status: 400,
+    detail: "The asset code does not conform to the Stellar asset format.",
+    retryable: false,
+    hint: "Asset codes are 1–12 alphanumeric characters. Native XLM has no code. Check spelling and try again."
+  },
+  missing_required_field: {
+    code: "missing_required_field",
+    type: uri("missing-required-field"),
+    title: "Missing Required Field",
+    status: 400,
+    detail: "A required input field was not provided.",
+    retryable: false,
+    hint: "Check the API or tool documentation for the list of required fields and supply all of them."
+  },
+
+  // ── Stellar account (404 / 400) ───────────────────────────────────────────
+  account_not_found: {
+    code: "account_not_found",
+    type: uri("account-not-found"),
+    title: "Stellar Account Not Found",
+    status: 404,
+    detail: "No account exists at this address on the selected network.",
+    retryable: false,
+    hint: "Verify the address and the active network (mainnet vs testnet). A new address must be funded before Horizon can locate it."
+  },
+  account_unfunded: {
+    code: "account_unfunded",
+    type: uri("account-unfunded"),
+    title: "Account Not Funded",
+    status: 400,
+    detail: "The account has not received its minimum XLM reserve and has never been activated.",
+    retryable: false,
+    hint: "Fund the account with at least the base reserve (currently 1 XLM) to activate it. Use the Testnet Faucet for testnet addresses."
+  },
+  account_merge_ineligible: {
+    code: "account_merge_ineligible",
+    type: uri("account-merge-ineligible"),
+    title: "Account Merge Ineligible",
+    status: 400,
+    detail: "The account cannot be merged because it still holds sub-entries or open trustlines.",
+    retryable: false,
+    hint: "Remove all offers, trustlines, and data entries from the account before attempting a merge."
+  },
+
+  // ── Stellar asset / trustline (404 / 400) ────────────────────────────────
+  asset_not_found: {
+    code: "asset_not_found",
+    type: uri("asset-not-found"),
+    title: "Asset Not Found",
+    status: 404,
+    detail: "The requested asset does not exist on the selected network.",
+    retryable: false,
+    hint: "Verify the asset code and issuer address. Ensure you are on the correct network."
+  },
+  trustline_missing: {
+    code: "trustline_missing",
+    type: uri("trustline-missing"),
+    title: "Trustline Missing",
+    status: 400,
+    detail: "The account does not have a trustline for the requested asset.",
+    retryable: false,
+    hint: "The receiving account must establish a trustline for the asset before it can hold a balance. Have the account send a Change Trust operation first."
+  },
+  trustline_limit_exceeded: {
+    code: "trustline_limit_exceeded",
+    type: uri("trustline-limit-exceeded"),
+    title: "Trustline Limit Exceeded",
+    status: 400,
+    detail: "The operation would exceed the trustline's configured limit.",
+    retryable: false,
+    hint: "Increase the trustline limit via a Change Trust operation, or reduce the amount being transferred."
+  },
+  trustline_no_issuer: {
+    code: "trustline_no_issuer",
+    type: uri("trustline-no-issuer"),
+    title: "Trustline Issuer Not Found",
+    status: 404,
+    detail: "The asset issuer account does not exist on the selected network.",
+    retryable: false,
+    hint: "Verify the issuer address. The asset may not be available on the active network."
+  },
+
+  // ── Stellar transaction (400 / 404) ───────────────────────────────────────
+  transaction_not_found: {
+    code: "transaction_not_found",
+    type: uri("transaction-not-found"),
+    title: "Transaction Not Found",
+    status: 404,
+    detail: "No transaction with that hash was found on the selected network.",
+    retryable: false,
+    hint: "Verify the transaction hash and the active network. Transactions can take several seconds to appear after submission."
+  },
+  transaction_malformed: {
+    code: "transaction_malformed",
+    type: uri("transaction-malformed"),
+    title: "Transaction Malformed",
+    status: 400,
+    detail: "The transaction envelope could not be decoded or is structurally invalid.",
+    retryable: false,
+    hint: "Ensure the transaction is encoded as a valid base64 XDR envelope. Use the XDR Inspector to diagnose encoding issues."
+  },
+  transaction_failed: {
+    code: "transaction_failed",
+    type: uri("transaction-failed"),
+    title: "Transaction Failed",
+    status: 400,
+    detail: "The transaction was submitted but rejected by the Stellar network.",
+    retryable: false,
+    hint: "Inspect the result codes to identify which operation failed. Use the Result Code Explainer for a plain-language breakdown."
+  },
+  sequence_mismatch: {
+    code: "sequence_mismatch",
+    type: uri("sequence-mismatch"),
+    title: "Sequence Number Mismatch",
+    status: 400,
+    detail: "The transaction sequence number does not match the account's current sequence.",
+    retryable: true,
+    hint: "Fetch the account's current sequence number and rebuild the transaction. This often occurs when multiple transactions are submitted in quick succession."
+  },
+  insufficient_fee: {
+    code: "insufficient_fee",
+    type: uri("insufficient-fee"),
+    title: "Insufficient Fee",
+    status: 400,
+    detail: "The base fee offered is below the network minimum.",
+    retryable: false,
+    hint: "Increase the transaction fee to meet the current network minimum. Check the Fee Stats tool for current surge pricing."
+  },
+  precondition_failed: {
+    code: "precondition_failed",
+    type: uri("precondition-failed"),
+    title: "Precondition Failed",
+    status: 400,
+    detail: "The transaction's time bounds or ledger sequence preconditions were not met.",
+    retryable: false,
+    hint: "Check the transaction's minTime/maxTime and min/maxLedger against the current ledger. Use the Preconditions Explainer for details."
+  },
+
+  // ── Soroban / smart-contract ──────────────────────────────────────────────
+  soroban_simulation_failed: {
+    code: "soroban_simulation_failed",
+    type: uri("soroban-simulation-failed"),
+    title: "Soroban Simulation Failed",
+    status: 400,
+    detail: "The Soroban transaction simulation did not succeed.",
+    retryable: false,
+    hint: "Review the simulation error code. Common causes: contract not found, host function trap, insufficient footprint. Use the Simulation Explainer for diagnostics."
+  },
+  soroban_invocation_failed: {
+    code: "soroban_invocation_failed",
+    type: uri("soroban-invocation-failed"),
+    title: "Soroban Contract Invocation Failed",
+    status: 400,
+    detail: "The Soroban contract invocation was rejected or trapped.",
+    retryable: false,
+    hint: "Check the contract error code and diagnostics events. The contract may have enforced a precondition or the arguments may be invalid."
+  },
+  soroban_resource_limit_exceeded: {
+    code: "soroban_resource_limit_exceeded",
+    type: uri("soroban-resource-limit-exceeded"),
+    title: "Soroban Resource Limit Exceeded",
+    status: 400,
+    detail: "The transaction exceeded its Soroban resource budget.",
+    retryable: false,
+    hint: "Increase the resource fee and footprint via simulation, or reduce the work performed by the contract invocation. Check the Fee Estimator tool."
+  },
+  soroban_contract_not_found: {
+    code: "soroban_contract_not_found",
+    type: uri("soroban-contract-not-found"),
+    title: "Soroban Contract Not Found",
+    status: 404,
+    detail: "No Soroban contract exists at the given contract ID on the selected network.",
+    retryable: false,
+    hint: "Verify the contract ID and the active network. Contracts are network-specific and must be deployed before they can be invoked."
+  },
+  xdr_decode_error: {
+    code: "xdr_decode_error",
+    type: uri("xdr-decode-error"),
+    title: "XDR Decode Error",
+    status: 400,
+    detail: "The input could not be decoded as valid Stellar XDR.",
+    retryable: false,
+    hint: "Verify that the input is valid base64-encoded XDR. Use the XDR Inspector to pinpoint the malformed section."
+  },
+  xdr_encode_error: {
+    code: "xdr_encode_error",
+    type: uri("xdr-encode-error"),
+    title: "XDR Encode Error",
+    status: 500,
+    detail: "A value could not be encoded to XDR.",
+    retryable: false,
+    hint: "Check that all values are within the valid range for their XDR type. File a bug report with the reproduction case."
+  },
+
+  // ── Horizon transport (mapped from HorizonErrorCode) ─────────────────────
+  horizon_not_found: {
+    code: "horizon_not_found",
+    type: uri("horizon-not-found"),
+    title: "Horizon: Resource Not Found",
+    status: 404,
+    detail: "The requested resource was not found on Horizon.",
+    retryable: false,
+    hint: "Verify the identifier (address, hash, ledger number) and the active network."
+  },
+  horizon_rate_limited: {
+    code: "horizon_rate_limited",
+    type: uri("horizon-rate-limited"),
+    title: "Horizon: Rate Limited",
+    status: 429,
+    detail: "Horizon is temporarily rate-limiting requests from this client.",
+    retryable: true,
+    hint: "Wait a moment before retrying. Consider caching results to reduce request frequency."
+  },
+  horizon_bad_request: {
+    code: "horizon_bad_request",
+    type: uri("horizon-bad-request"),
+    title: "Horizon: Bad Request",
+    status: 400,
+    detail: "Horizon rejected the request because the supplied value was invalid.",
+    retryable: false,
+    hint: "Check the parameter format against the Horizon documentation and try again."
+  },
+  horizon_server_error: {
+    code: "horizon_server_error",
+    type: uri("horizon-server-error"),
+    title: "Horizon: Server Error",
+    status: 503,
+    detail: "Horizon is temporarily unavailable.",
+    retryable: true,
+    hint: "Check the Horizon Health tool or https://stellarbeat.io for network status. Try again shortly."
+  },
+  horizon_network_unavailable: {
+    code: "horizon_network_unavailable",
+    type: uri("horizon-network-unavailable"),
+    title: "Horizon: Network Unavailable",
+    status: 503,
+    detail: "The connection to Horizon could not be established.",
+    retryable: true,
+    hint: "Check your internet connection and try again. If the problem persists, verify the Horizon URL in settings."
+  },
+  horizon_timeout: {
+    code: "horizon_timeout",
+    type: uri("horizon-timeout"),
+    title: "Horizon: Request Timeout",
+    status: 504,
+    detail: "Horizon did not respond within the allowed time.",
+    retryable: true,
+    hint: "Try again. If timeouts are frequent, check the Horizon Health tool for elevated response times."
+  },
+  horizon_unknown: {
+    code: "horizon_unknown",
+    type: uri("horizon-unknown"),
+    title: "Horizon: Unknown Error",
+    status: 500,
+    detail: "An unclassified error was returned by Horizon.",
+    retryable: false,
+    hint: "Try again. If the error persists, record the correlation ID and report it."
+  },
+
+  // ── Soroban RPC transport ─────────────────────────────────────────────────
+  rpc_parse_error: {
+    code: "rpc_parse_error",
+    type: uri("rpc-parse-error"),
+    title: "RPC: Parse Error",
+    status: 400,
+    detail: "The Soroban RPC endpoint could not parse the request.",
+    retryable: false,
+    hint: "Ensure the JSON-RPC request is well-formed and the method parameters match the expected schema."
+  },
+  rpc_invalid_request: {
+    code: "rpc_invalid_request",
+    type: uri("rpc-invalid-request"),
+    title: "RPC: Invalid Request",
+    status: 400,
+    detail: "The Soroban RPC request was structurally invalid.",
+    retryable: false,
+    hint: "Check the JSON-RPC envelope: jsonrpc, id, method and params must all be present and correctly typed."
+  },
+  rpc_method_not_found: {
+    code: "rpc_method_not_found",
+    type: uri("rpc-method-not-found"),
+    title: "RPC: Method Not Found",
+    status: 404,
+    detail: "The requested Soroban RPC method does not exist on this node.",
+    retryable: false,
+    hint: "Verify the method name against the Soroban RPC specification. The node may be running an older protocol version."
+  },
+  rpc_invalid_params: {
+    code: "rpc_invalid_params",
+    type: uri("rpc-invalid-params"),
+    title: "RPC: Invalid Parameters",
+    status: 400,
+    detail: "The parameters supplied to the Soroban RPC method are invalid.",
+    retryable: false,
+    hint: "Check the parameter names and value types against the Soroban RPC documentation."
+  },
+  rpc_server_error: {
+    code: "rpc_server_error",
+    type: uri("rpc-server-error"),
+    title: "RPC: Server Error",
+    status: 503,
+    detail: "The Soroban RPC node returned an internal error.",
+    retryable: true,
+    hint: "Try again. If the error persists, check node status or switch to a different RPC endpoint."
+  },
+  rpc_network_unavailable: {
+    code: "rpc_network_unavailable",
+    type: uri("rpc-network-unavailable"),
+    title: "RPC: Network Unavailable",
+    status: 503,
+    detail: "The connection to the Soroban RPC node could not be established.",
+    retryable: true,
+    hint: "Check your internet connection and the configured RPC URL."
+  },
+  rpc_timeout: {
+    code: "rpc_timeout",
+    type: uri("rpc-timeout"),
+    title: "RPC: Request Timeout",
+    status: 504,
+    detail: "The Soroban RPC node did not respond within the allowed time.",
+    retryable: true,
+    hint: "Try again. Soroban operations involving large footprints can take longer; consider increasing the client timeout."
+  },
+  rpc_unknown: {
+    code: "rpc_unknown",
+    type: uri("rpc-unknown"),
+    title: "RPC: Unknown Error",
+    status: 500,
+    detail: "An unclassified error was returned by the Soroban RPC node.",
+    retryable: false,
+    hint: "Try again. If the error persists, record the correlation ID and report it."
+  },
+
+  // ── Internal / unclassified ───────────────────────────────────────────────
+  internal_error: {
+    code: "internal_error",
+    type: uri("internal-error"),
+    title: "Internal Error",
+    status: 500,
+    detail: "An unexpected internal error occurred.",
+    retryable: true,
+    hint: "Try again. If the problem persists, contact support with the correlation ID."
+  }
+} as const satisfies Record<ProblemCode, ProblemDefinition>;
+
+// ─── Public helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Look up the full `ProblemDefinition` for a stable code.
+ */
+export function getProblemDefinition(code: ProblemCode): ProblemDefinition {
+  return PROBLEM_CODES[code];
+}
+
+/**
+ * Whether a problem code indicates the operation is safe to retry.
+ */
+export function isProblemRetryable(code: ProblemCode): boolean {
+  return PROBLEM_CODES[code].retryable;
+}
+
+/**
+ * Creates a `ProblemDetails` envelope from a `ProblemCode`.
+ *
+ * The `detail` field defaults to the safe message in the taxonomy; pass
+ * `overrideDetail` only with a pre-sanitised, non-user-input string.
+ */
+export function problemDetailsFromCode(
+  code: ProblemCode,
+  options: {
+    overrideDetail?: string;
+    correlationId?: string;
+    instance?: string;
+    extensions?: Record<string, unknown>;
+  } = {}
+): ProblemDetails {
+  const def = PROBLEM_CODES[code];
+  return {
+    type: def.type,
+    title: def.title,
+    status: def.status,
+    detail: options.overrideDetail ?? def.detail,
+    instance: options.instance,
+    code: def.code,
+    retryable: def.retryable,
+    hint: def.hint,
+    correlationId: options.correlationId,
+    extensions: options.extensions
+  };
+}
+
+// ─── Bridge adapters ──────────────────────────────────────────────────────────
+
+import type { HorizonErrorClassification, HorizonErrorCode } from "@/core/horizon/errors";
+import type { RpcErrorClassification } from "@/core/rpc/errors";
+
+/** Maps the existing HorizonErrorCode to the new ProblemCode taxonomy. */
+const HORIZON_CODE_MAP: Record<HorizonErrorCode, ProblemCode> = {
+  not_found: "horizon_not_found",
+  rate_limited: "horizon_rate_limited",
+  bad_request: "horizon_bad_request",
+  server_error: "horizon_server_error",
+  network_unavailable: "horizon_network_unavailable",
+  timeout: "horizon_timeout",
+  unknown: "horizon_unknown"
+};
+
+/**
+ * Converts a `HorizonErrorClassification` (from `classifyHorizonError`) into a
+ * `ProblemDetails` envelope.
+ *
+ * The `detail` field is taken from the taxonomy's safe message, not from the
+ * raw Horizon response, so no server-supplied text is forwarded to the caller.
+ */
+export function horizonToProblemDetails(
+  classified: HorizonErrorClassification,
+  options: { instance?: string; extensions?: Record<string, unknown> } = {}
+): ProblemDetails {
+  const code = HORIZON_CODE_MAP[classified.code];
+  return problemDetailsFromCode(code, {
+    correlationId: classified.correlationId,
+    instance: options.instance,
+    extensions: options.extensions
+  });
+}
+
+/**
+ * Converts a `RpcErrorClassification` (from `classifyRpcError`) into a
+ * `ProblemDetails` envelope.
+ */
+export function rpcToProblemDetails(
+  classified: RpcErrorClassification,
+  options: { instance?: string; extensions?: Record<string, unknown> } = {}
+): ProblemDetails {
+  return problemDetailsFromCode(classified.problemCode, {
+    correlationId: classified.correlationId,
+    instance: options.instance,
+    extensions: options.extensions
+  });
+}
diff --git a/core/rpc/errors.ts b/core/rpc/errors.ts
new file mode 100644
index 0000000..abd7cd4
--- /dev/null
+++ b/core/rpc/errors.ts
@@ -0,0 +1,163 @@
+/**
+ * Soroban RPC failure taxonomy.
+ *
+ * Maps JSON-RPC error codes (from `core/rpc/client.ts`) and transport failures
+ * to stable `ProblemCode` values. Every feature that calls Soroban RPC should
+ * map its transport errors through `classifyRpcError` so error handling stays
+ * consistent across slices.
+ *
+ * Safe-message invariants
+ * ───────────────────────
+ * - `safeMessage` is always derived from the internal taxonomy; raw RPC error
+ *   messages are never forwarded to the caller.
+ * - `rawCode` and `rawMessage` are carried internally for diagnostics but must
+ *   not be rendered in user-facing UI.
+ */
+
+import { RPC_STANDARD_CODES, type JsonRpcFailure } from "@/core/rpc/client";
+import type { ProblemCode } from "@/core/errors/problem-details";
+
+export type RpcErrorCode =
+  | "rpc_parse_error"
+  | "rpc_invalid_request"
+  | "rpc_method_not_found"
+  | "rpc_invalid_params"
+  | "rpc_server_error"
+  | "rpc_network_unavailable"
+  | "rpc_timeout"
+  | "rpc_unknown";
+
+export interface RpcErrorClassification {
+  /** Stable Utix error code (matches ProblemCode). */
+  code: RpcErrorCode;
+  /** The ProblemCode this maps to (always identical to `code` for RPC errors). */
+  problemCode: ProblemCode;
+  /** Whether the caller can safely retry. */
+  retryable: boolean;
+  /** Safe, pre-sanitised message; never echoes raw RPC error text. */
+  safeMessage: string;
+  /** Correlation ID for tracing. */
+  correlationId: string;
+  /**
+   * Internal diagnostics only — never render in user-facing UI.
+   * Carries the original JSON-RPC error code for logging.
+   */
+  rawCode?: number;
+}
+
+const safeMessages: Record<RpcErrorCode, string> = {
+  rpc_parse_error:
+    "The Soroban RPC request could not be parsed. Check the request format and try again.",
+  rpc_invalid_request:
+    "The Soroban RPC request was invalid. Check the JSON-RPC envelope and try again.",
+  rpc_method_not_found:
+    "The requested Soroban RPC method does not exist on this node.",
+  rpc_invalid_params:
+    "The parameters supplied to the Soroban RPC method are invalid.",
+  rpc_server_error:
+    "The Soroban RPC node returned an internal error. Try again shortly.",
+  rpc_network_unavailable:
+    "The connection to the Soroban RPC node could not be established. Check your connection.",
+  rpc_timeout:
+    "The Soroban RPC node did not respond in time. Try again.",
+  rpc_unknown:
+    "An unexpected error was returned by the Soroban RPC node. Try again or contact support."
+};
+
+const retryable: Record<RpcErrorCode, boolean> = {
+  rpc_parse_error: false,
+  rpc_invalid_request: false,
+  rpc_method_not_found: false,
+  rpc_invalid_params: false,
+  rpc_server_error: true,
+  rpc_network_unavailable: true,
+  rpc_timeout: true,
+  rpc_unknown: false
+};
+
+function correlationId(): string {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `rpc-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Classifies a raw JSON-RPC error code (from `RPC_STANDARD_CODES` or an HTTP
+ * status) into a stable `RpcErrorClassification`.
+ */
+function classifyRpcCode(code: number): RpcErrorCode {
+  switch (code) {
+    case RPC_STANDARD_CODES.PARSE_ERROR:
+      return "rpc_parse_error";
+    case RPC_STANDARD_CODES.INVALID_REQUEST:
+    case RPC_STANDARD_CODES.MALFORMED_ENVELOPE:
+      return "rpc_invalid_request";
+    case RPC_STANDARD_CODES.METHOD_NOT_FOUND:
+      return "rpc_method_not_found";
+    case RPC_STANDARD_CODES.INVALID_PARAMS:
+      return "rpc_invalid_params";
+    case RPC_STANDARD_CODES.INTERNAL_ERROR:
+      return "rpc_server_error";
+    default:
+      // HTTP 429 → rate-limit → treat as server-side and retryable
+      if (code === 429) return "rpc_server_error";
+      // HTTP 5xx range
+      if (code >= 500 && code < 600) return "rpc_server_error";
+      return "rpc_unknown";
+  }
+}
+
+/**
+ * Classifies a `JsonRpcFailure` into a stable `RpcErrorClassification`.
+ *
+ * The raw error message in the `JsonRpcFailure` is intentionally dropped;
+ * callers receive only the safe taxonomy message.
+ */
+export function classifyRpcError(failure: JsonRpcFailure): RpcErrorClassification {
+  const rpcCode = classifyRpcCode(failure.error.code);
+  return {
+    code: rpcCode,
+    problemCode: rpcCode as ProblemCode,
+    retryable: retryable[rpcCode],
+    safeMessage: safeMessages[rpcCode],
+    correlationId: correlationId(),
+    rawCode: failure.error.code
+  };
+}
+
+/**
+ * Classifies a transport-level failure (network error, abort, timeout) into a
+ * stable `RpcErrorClassification`.
+ *
+ * Pass the raw `Error` object; only the error type is inspected, never the
+ * message text, which may contain user data or internal paths.
+ */
+export function classifyRpcTransportError(error: unknown): RpcErrorClassification {
+  let rpcCode: RpcErrorCode = "rpc_unknown";
+
+  if (error instanceof Error) {
+    const name = error.name.toLowerCase();
+    const message = error.message.toLowerCase();
+
+    if (name === "aborterror" || message.includes("abort")) {
+      rpcCode = "rpc_timeout";
+    } else if (
+      name === "typeerror" ||
+      message.includes("fetch") ||
+      message.includes("network") ||
+      message.includes("failed to fetch")
+    ) {
+      rpcCode = "rpc_network_unavailable";
+    } else if (message.includes("timeout") || message.includes("timed out")) {
+      rpcCode = "rpc_timeout";
+    }
+  }
+
+  return {
+    code: rpcCode,
+    problemCode: rpcCode as ProblemCode,
+    retryable: retryable[rpcCode],
+    safeMessage: safeMessages[rpcCode],
+    correlationId: correlationId()
+  };
+}
diff --git a/docs/PROBLEM_DETAILS.md b/docs/PROBLEM_DETAILS.md
new file mode 100644
index 0000000..d1c74fd
--- /dev/null
+++ b/docs/PROBLEM_DETAILS.md
@@ -0,0 +1,305 @@
+# Problem Details Taxonomy
+
+Utix uses a stable machine-code taxonomy for all API errors, following
+[RFC 7807 Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807).
+This document is the single source of truth for the taxonomy, the wire shape,
+the stability contract, and the operational edge cases.
+
+Drift tests in `core/errors/__tests__/problem-details.contract.test.ts` enforce
+that nothing here changes accidentally.
+
+## Wire shape — `ProblemDetails`
+
+Every error response carries this shape:
+
+```json
+{
+  "type":          "https://utix.dev/problems/account-not-found",
+  "title":         "Stellar Account Not Found",
+  "status":        404,
+  "detail":        "No account exists at this address on the selected network.",
+  "code":          "account_not_found",
+  "retryable":     false,
+  "hint":          "Verify the address and the active network (mainnet vs testnet)…",
+  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
+  "instance":      "/tools/balance-viewer?address=G…",
+  "extensions":    { "network": "testnet" }
+}
+```
+
+| Field           | Required | Type      | Notes                                        |
+|-----------------|----------|-----------|----------------------------------------------|
+| `type`          | ✓        | `string`  | Absolute URI; stable across releases.         |
+| `title`         | ✓        | `string`  | Short summary. May change in future releases. |
+| `status`        | ✓        | `number`  | HTTP status code (400–599).                  |
+| `detail`        | ✓        | `string`  | Safe, sanitised, instance-specific message.  |
+| `code`          | ✓        | `string`  | Stable lowercase_snake identifier.           |
+| `retryable`     | ✓        | `boolean` | Whether repeating the request is safe.       |
+| `hint`          | ✓        | `string`  | Actionable remediation for developers.       |
+| `correlationId` | —        | `string`  | Passed through from the transport layer.     |
+| `instance`      | —        | `string`  | URI to the resource that triggered the error.|
+| `extensions`    | —        | `object`  | Non-breaking open-ended additions.           |
+
+### Stability contract
+
+- The seven **required** fields will never be removed or change type.
+- `code` values are **permanent**. To evolve meaning, add a new code.
+- `type` URIs are **permanent** and resolve to this documentation.
+- `hint` and `detail` text may be improved over time, but semantics are stable.
+- `extensions` fields are additive; consumers must ignore unknown keys.
+
+## Code taxonomy
+
+All codes are `lowercase_snake`. The full set lives in
+`core/errors/problem-details.ts` → `PROBLEM_CODES`.
+
+### Validation (400)
+
+| Code                    | Title                       | Retryable |
+|-------------------------|-----------------------------|-----------|
+| `validation_error`      | Validation Error            | no        |
+| `invalid_address`       | Invalid Stellar Address     | no        |
+| `invalid_amount`        | Invalid Amount              | no        |
+| `invalid_asset_code`    | Invalid Asset Code          | no        |
+| `missing_required_field`| Missing Required Field      | no        |
+
+### Stellar Account (400/404)
+
+| Code                      | Title                        | Retryable |
+|---------------------------|------------------------------|-----------|
+| `account_not_found`       | Stellar Account Not Found    | no        |
+| `account_unfunded`        | Account Not Funded           | no        |
+| `account_merge_ineligible`| Account Merge Ineligible     | no        |
+
+### Stellar Asset / Trustline (400/404)
+
+| Code                     | Title                          | Retryable |
+|--------------------------|--------------------------------|-----------|
+| `asset_not_found`        | Asset Not Found                | no        |
+| `trustline_missing`      | Trustline Missing              | no        |
+| `trustline_limit_exceeded`| Trustline Limit Exceeded      | no        |
+| `trustline_no_issuer`    | Trustline Issuer Not Found     | no        |
+
+### Stellar Transaction (400/404)
+
+| Code                     | Title                          | Retryable |
+|--------------------------|--------------------------------|-----------|
+| `transaction_not_found`  | Transaction Not Found          | no        |
+| `transaction_malformed`  | Transaction Malformed          | no        |
+| `transaction_failed`     | Transaction Failed             | no        |
+| `sequence_mismatch`      | Sequence Number Mismatch       | **yes**   |
+| `insufficient_fee`       | Insufficient Fee               | no        |
+| `precondition_failed`    | Precondition Failed            | no        |
+
+### Soroban / Smart Contract (400/404/500)
+
+| Code                           | Title                              | Retryable |
+|--------------------------------|------------------------------------|-----------|
+| `soroban_simulation_failed`    | Soroban Simulation Failed          | no        |
+| `soroban_invocation_failed`    | Soroban Contract Invocation Failed | no        |
+| `soroban_resource_limit_exceeded`| Soroban Resource Limit Exceeded  | no        |
+| `soroban_contract_not_found`   | Soroban Contract Not Found         | no        |
+| `xdr_decode_error`             | XDR Decode Error                   | no        |
+| `xdr_encode_error`             | XDR Encode Error                   | no        |
+
+### Horizon Transport (400/404/429/503/504)
+
+| Code                        | Title                          | Retryable |
+|-----------------------------|--------------------------------|-----------|
+| `horizon_not_found`         | Horizon: Resource Not Found    | no        |
+| `horizon_rate_limited`      | Horizon: Rate Limited          | **yes**   |
+| `horizon_bad_request`       | Horizon: Bad Request           | no        |
+| `horizon_server_error`      | Horizon: Server Error          | **yes**   |
+| `horizon_network_unavailable`| Horizon: Network Unavailable  | **yes**   |
+| `horizon_timeout`           | Horizon: Request Timeout       | **yes**   |
+| `horizon_unknown`           | Horizon: Unknown Error         | no        |
+
+### Soroban RPC Transport (400/404/503/504)
+
+| Code                       | Title                           | Retryable |
+|----------------------------|---------------------------------|-----------|
+| `rpc_parse_error`          | RPC: Parse Error                | no        |
+| `rpc_invalid_request`      | RPC: Invalid Request            | no        |
+| `rpc_method_not_found`     | RPC: Method Not Found           | no        |
+| `rpc_invalid_params`       | RPC: Invalid Parameters         | no        |
+| `rpc_server_error`         | RPC: Server Error               | **yes**   |
+| `rpc_network_unavailable`  | RPC: Network Unavailable        | **yes**   |
+| `rpc_timeout`              | RPC: Request Timeout            | **yes**   |
+| `rpc_unknown`              | RPC: Unknown Error              | no        |
+
+### Internal (500)
+
+| Code             | Title          | Retryable |
+|------------------|----------------|-----------|
+| `internal_error` | Internal Error | **yes**   |
+
+## Public API entry points
+
+### `problemDetailsFromCode(code, options?)`
+
+```ts
+import { problemDetailsFromCode } from "@/core/errors/problem-details";
+
+const pd = problemDetailsFromCode("account_not_found", {
+  correlationId: "cid-123",
+  instance: "/tools/balance-viewer?address=GABC…",
+  extensions: { network: "testnet" }
+});
+```
+
+### `horizonToProblemDetails(classified, options?)`
+
+Bridges a `HorizonErrorClassification` (from `classifyHorizonError`) into a
+`ProblemDetails` envelope without forwarding any raw Horizon error text.
+
+```ts
+import { classifyHorizonError } from "@/core/horizon/errors";
+import { horizonToProblemDetails } from "@/core/errors/problem-details";
+
+try {
+  const data = await horizonClient.accounts().accountId(address).call();
+} catch (err) {
+  const classified = classifyHorizonError(err);
+  const pd = horizonToProblemDetails(classified, { instance: "/tools/balance-viewer" });
+  // pd.code === "horizon_not_found", pd.retryable === false, etc.
+}
+```
+
+### `rpcToProblemDetails(classified, options?)`
+
+Bridges a `RpcErrorClassification` (from `classifyRpcError` or
+`classifyRpcTransportError`) into a `ProblemDetails` envelope.
+
+```ts
+import { classifyRpcError, classifyRpcTransportError } from "@/core/rpc/errors";
+import { rpcToProblemDetails } from "@/core/errors/problem-details";
+import { isRpcFailure, sorobanRpc } from "@/core/rpc/client";
+
+const response = await sorobanRpc<SimulateTransactionResult>("simulateTransaction", params);
+if (isRpcFailure(response)) {
+  const classified = classifyRpcError(response);
+  const pd = rpcToProblemDetails(classified);
+}
+```
+
+## Safe-message invariants
+
+1. **No user input is echoed.** The `detail` and `hint` fields are always
+   derived from the taxonomy, not from user-supplied values.
+2. **No raw transport errors are forwarded.** `classifyHorizonError` and
+   `classifyRpcError` discard the raw server error text; only the safe taxonomy
+   message is surfaced.
+3. **`rawCode`** in `RpcErrorClassification` is for internal logging only and
+   must never be rendered in user-facing UI.
+
+## Operational edge cases
+
+### Horizon `unknown` code
+
+`classifyHorizonError` assigns `code: "unknown"` when no HTTP status is
+available and the error message does not match known patterns. This maps to
+`horizon_unknown` in the problem-details taxonomy.
+
+**Action:** Log the `correlationId`, check Horizon network status, and treat it
+as non-retryable until the root cause is identified.
+
+### Soroban simulation failures vs invocation failures
+
+`soroban_simulation_failed` (status 400) means the RPC node rejected the
+transaction during preflight — the transaction was never applied. This is always
+non-retryable without changing the transaction.
+
+`soroban_invocation_failed` means the contract trapped at runtime. Inspect the
+diagnostic events for the specific trap code.
+
+### Sequence mismatch (`sequence_mismatch`)
+
+This is the only transaction-construction code marked `retryable: true`. After
+a 400 with this code, fetch the account's current sequence number, rebuild the
+transaction, and resubmit. Do **not** simply increment the sequence; always
+fetch the latest from Horizon.
+
+### RPC timeout vs network unavailable
+
+`rpc_timeout` indicates the node was reachable but did not respond in time.
+`rpc_network_unavailable` indicates a pre-flight failure (DNS, TCP connect).
+Both are retryable; `rpc_timeout` may benefit from a longer client timeout.
+
+### Rate limiting (`horizon_rate_limited`)
+
+Horizon returns HTTP 429. The `retryable: true` flag indicates the request
+can be repeated after a back-off. Use an exponential back-off with jitter.
+The Horizon Health tool shows real-time rate-limit thresholds.
+
+## Failure modes and rollback
+
+### Rolling back the taxonomy (removing a code)
+
+**Never remove a code once it is shipped.** Downstream consumers may
+`switch` on the `code` field; a missing case will fall through to their default
+handler, producing silent misclassification.
+
+To deprecate a code:
+
+1. Add a `@deprecated superseded by <new-code>` JSDoc comment to the entry in
+   `PROBLEM_CODES`.
+2. Keep the entry in `PROBLEM_CODES` indefinitely.
+3. Update any internal classification logic to produce the new code.
+4. In a future major version (with a migration plan), the old code may map to
+   the new one as a redirect alias.
+
+### Rolling back the ProblemDetails shape (changing a required field)
+
+Any change to the seven required fields is a **breaking change**:
+
+1. Update `docs/API_CONTRACT.md` with the new shape.
+2. Update `problemDetailsSchema` in
+   `core/errors/__tests__/problem-details.contract.test.ts`.
+3. Bump the schema version in the contract.
+4. Document the migration path for consumers.
+
+### Recovering from a bad deployment
+
+If a deployment ships with incorrect `code` values or malformed `type` URIs:
+
+1. The contract drift tests in CI will fail immediately on the next run.
+2. Revert the offending commit: `git revert <sha>`.
+3. Run `npm run verify:contract` locally to confirm the revert restores the
+   locked shape.
+4. Re-deploy the reverted build.
+
+No data is mutated by the problem-details module (it is read-only) so there
+is no database or cache to repair.
+
+### Unknown code at runtime
+
+If a caller receives a `code` it does not recognise (e.g., after a partial
+upgrade), it should:
+
+1. Treat the response as a non-retryable error.
+2. Display the `detail` and `hint` fields verbatim to the user.
+3. Log the unknown `code` and `correlationId` for investigation.
+
+New codes are always additive (never replace old ones), so an unrecognised code
+means the consumer is running an older version.
+
+## Drift prevention
+
+`npm run verify:contract` runs all tests under `core/contract/`. The
+problem-details contract tests are in `core/errors/__tests__/` and are picked
+up by the standard `npm test` run.
+
+To run only the problem-details tests:
+
+```bash
+npm test -- core/errors
+```
+
+Checks enforced:
+
+- Every required field is present and correctly typed.
+- Every code in the exhaustive list exists in `PROBLEM_CODES`.
+- The total count matches (catches silent additions and deletions).
+- Every `type` URI starts with `https://utix.dev/problems/`.
+- No raw Horizon/RPC error text appears in `detail` or `safeMessage`.
+- The Horizon and RPC bridge adapters produce valid envelopes for all known codes.