@stapel/search-react 0.1.0

package/src/headless/SearchProvider.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { ModuleProvider } from "../model/context.js";
+import type { SearchRuntime } from "../model/runtime.js";
+
+/**
+ * Provides the wired {@link SearchRuntime} to every search hook and headless
+ * component below it. Bring your own visual shell — this component renders
+ * nothing of its own. (Core's `createModuleContext` provider, bound to this
+ * pair — slim wave §21/S2.)
+ *
+ * ```tsx
+ * const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <SearchProvider runtime={runtime}>{app}</SearchProvider>
+ * ```
+ */
+export const SearchProvider: (props: {
+  runtime: SearchRuntime;
+  children: ReactNode;
+}) => ReactElement = ModuleProvider;

package/src/headless/SearchResults.tsx

@@ -0,0 +1,149 @@
+import { useCallback } from "react";
+import type { ReactNode } from "react";
+import {
+  actionAvailable,
+  actionBlocked,
+  actionBlockedByFailure,
+  loadStateFromQuery,
+  mapLoad,
+} from "@stapel/core";
+import type { ActionAvailability, LoadState, StapelApiError } from "@stapel/core";
+import type {
+  SearchDegradation,
+  SearchItem,
+  SearchResponse,
+} from "../api/types.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { useSearchQuery } from "../model/queries.js";
+import { countIsEstimate, parseDegradations } from "../state/degradations.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+/** What the envelope says about this page, beside the rows. */
+export interface SearchPageInfo {
+  /** Total matches — an ESTIMATE unless {@link SearchPageInfo.exactTotal}. */
+  readonly count: number;
+  readonly exactTotal: boolean;
+  /** `true` when `count` must be rendered as approximate ("≈", "about"). */
+  readonly countIsEstimate: boolean;
+  readonly hasNext: boolean;
+  readonly hasPrev: boolean;
+  /** The sort the SERVER applied — which may not be the one requested when
+   * none was requested at all (it picks relevance with text, newest without). */
+  readonly sort: string;
+  readonly backend: string;
+  readonly tookMs: number;
+  /** How many of this page's rows are promoted (DSA Art. 26 marking). */
+  readonly promotedCount: number;
+}
+
+/** The bag `<SearchResults>` hands its render prop. */
+export interface SearchResultsBag {
+  /**
+   * The page's rows as a state a skin cannot flatten. Render with core's
+   * `matchList` — its four arms are what keeps "nothing found" a sentence
+   * that can only be said about a search that actually ran. The 2026-08-09
+   * incident was this exact substitution.
+   */
+  readonly state: LoadState<readonly SearchItem[]>;
+  /** The whole envelope, for a skin that needs a field this bag does not
+   * lift. Same load discipline. */
+  readonly envelope: LoadState<SearchResponse>;
+  /** `null` until the page has landed. */
+  readonly page: SearchPageInfo | null;
+  /**
+   * What the engine could not do for this query, de-duplicated. Rendered as a
+   * banner, never swallowed: a page that hides "counts are approximate" is
+   * claiming a precision the backend explicitly disclaimed.
+   */
+  readonly degradations: readonly SearchDegradation[];
+  /** A refetch is in flight over rows already on screen. */
+  readonly isFetching: boolean;
+  /** The last refusal, for a skin that renders the code's own sentence.
+   * `error.400.search_window_exceeded` is "narrow the search", not "nothing
+   * found" — the two must not share a branch. */
+  readonly error: StapelApiError | null;
+  /** Blocked WITH A REASON at the last page, never a bare disabled button. */
+  readonly next: ActionAvailability;
+  readonly prev: ActionAvailability;
+  goNext(): void;
+  goPrev(): void;
+  refetch(): void;
+}
+
+/**
+ * Headless result page — the rows, the keyset controls, and the envelope's
+ * honesty block. Renderless: it decides nothing about how any of that looks.
+ *
+ * Pagination is KEYSET (`anchor`/`direction`), not offset: there is no page
+ * number to jump to, and depth is capped server-side by `MAX_RESULT_WINDOW`
+ * (a cursor past it answers `error.400.search_window_exceeded`). Both facts
+ * are the backend's, and both are surfaced rather than papered over.
+ */
+export function SearchResults(props: {
+  /** Skip the request (e.g. while the host is still resolving a category). */
+  enabled?: boolean;
+  children: (bag: SearchResultsBag) => ReactNode;
+}): ReactNode {
+  const { state: searchState, goToAnchor } = useSearchState();
+  const query = useSearchQuery(
+    searchState,
+    props.enabled !== undefined ? { enabled: props.enabled } : undefined
+  );
+
+  const envelope = loadStateFromQuery(query);
+  const rows = mapLoad(envelope, (data) => data.items as readonly SearchItem[]);
+  const data = envelope.status === "ready" ? envelope.data : null;
+
+  const degradations = parseDegradations(data?.degraded);
+
+  const page: SearchPageInfo | null =
+    data === null
+      ? null
+      : {
+          count: data.count,
+          exactTotal: data.exact_total,
+          countIsEstimate: countIsEstimate(data.exact_total, degradations),
+          hasNext: data.has_next,
+          hasPrev: data.has_prev,
+          sort: data.sort,
+          backend: data.backend,
+          tookMs: data.took_ms,
+          promotedCount: data.items.filter((item) => item.promoted).length,
+        };
+
+  const blockFor = (
+    hasMore: boolean,
+    code: string
+  ): ActionAvailability => {
+    if (envelope.status === "loading") return actionBlocked("stapel.action.blocked.loading");
+    if (envelope.status === "failed") return actionBlockedByFailure(envelope.error);
+    return hasMore ? actionAvailable() : actionBlocked(code);
+  };
+
+  const goNext = useCallback(() => {
+    if (data?.next_anchor != null) goToAnchor(data.next_anchor, "next");
+  }, [data, goToAnchor]);
+
+  const goPrev = useCallback(() => {
+    // `prev_anchor` is emitted only when there IS a previous page; when the
+    // person is walking back to the first one the server sends none, and
+    // clearing the cursor is what "page 1" means under keyset paging.
+    if (data?.has_prev === true) goToAnchor(data.prev_anchor, "prev");
+  }, [data, goToAnchor]);
+
+  return props.children({
+    state: rows,
+    envelope,
+    page,
+    degradations,
+    isFetching: query.isFetching,
+    error: query.error ?? null,
+    next: blockFor(data?.has_next === true, SEARCH_I18N_KEYS.resultsBlockedAtEnd),
+    prev: blockFor(data?.has_prev === true, SEARCH_I18N_KEYS.resultsBlockedAtStart),
+    goNext,
+    goPrev,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/headless/SearchStateProvider.tsx

@@ -0,0 +1,175 @@
+import { createContext, useCallback, useContext, useMemo } from "react";
+import type { ReactElement, ReactNode } from "react";
+import type {
+  SearchGeo,
+  SearchQueryState,
+  SearchRange,
+} from "../api/types.js";
+import {
+  activeFilterCount,
+  clearFilters,
+  parseSearchState,
+  patchSearchState,
+  setFilterValues,
+  setRangeValue,
+  toggleFilterValue,
+  writeSearchState,
+} from "../state/urlState.js";
+import type {
+  ParseSearchStateOptions,
+  SearchStateIssue,
+  SearchStatePatch,
+} from "../state/urlState.js";
+
+/**
+ * THE ROUTER SEAM.
+ *
+ * Two members, and they are exactly the shape react-router v7's
+ * `useSearchParams()` returns — so binding one is a one-liner (`./router`
+ * ships it). The seam exists so the main entry carries no router: a Next.js
+ * host, a hash-router host, or a server-rendered page that reads
+ * `new URL(request.url).searchParams` all satisfy it, and the pair stays
+ * honest about the fact that URL state is a ROUTER concern it does not own.
+ */
+export interface SearchParamsAdapter {
+  readonly params: URLSearchParams;
+  /**
+   * Write the next query string.
+   *
+   * `replace` is meaningful, not decorative: a FILTER change pushes (so Back
+   * removes exactly the last filter — the spec's §4.2 acceptance), while a
+   * correction that the person did not perform replaces. Callers below pass
+   * it deliberately; an adapter that ignores it breaks the Back button.
+   */
+  setParams(next: URLSearchParams, options?: { readonly replace?: boolean }): void;
+}
+
+/** Everything a control needs to read and move the search. */
+export interface SearchStateBag {
+  /** The current state, parsed from the URL. Nothing else holds a copy. */
+  readonly state: SearchQueryState;
+  /** What the URL carried that could not be read (see `SearchStateIssue`). */
+  readonly issues: readonly SearchStateIssue[];
+  /** Facet values + ranges + geo the person has applied. */
+  readonly activeFilters: number;
+
+  setText(q: string): void;
+  setSort(sort: string | null): void;
+  setCategory(category: string | null): void;
+  setLanguage(lang: string | null): void;
+  toggleFilter(slug: string, value: string): void;
+  setFilter(slug: string, values: readonly string[]): void;
+  setRange(slug: string, range: SearchRange | null): void;
+  setGeo(geo: SearchGeo | null): void;
+  setLimit(limit: number | null): void;
+  clearAll(): void;
+  /** Move to a keyset page. The ONLY mutator that keeps a cursor. */
+  goToAnchor(anchor: string | null, direction: "next" | "prev"): void;
+  /** Escape hatch for a host control this pair does not ship. Goes through
+   * `patchSearchState`, so it drops the cursor like every other change. */
+  patch(patch: SearchStatePatch): void;
+}
+
+const StateContext = createContext<SearchStateBag | null>(null);
+
+export interface SearchStateProviderProps extends ParseSearchStateOptions {
+  readonly adapter: SearchParamsAdapter;
+  readonly children: ReactNode;
+}
+
+/**
+ * Binds the URL to the search state. Every control below reads and writes
+ * through {@link useSearchState}; no component holds a second copy of a
+ * filter, which is what makes "copy the link into another tab" produce the
+ * same page by construction rather than by discipline.
+ */
+export function SearchStateProvider(
+  props: SearchStateProviderProps
+): ReactElement {
+  const { adapter, children, ...parseOptions } = props;
+  const { params, setParams } = adapter;
+
+  // The parse options are spread into a stable dependency: a host that builds
+  // the object inline (the normal way to write it) must not reparse on every
+  // render and hand every consumer a new state object.
+  const {
+    defaultType,
+    defaultQ,
+    defaultSort,
+    defaultLimit,
+    defaultCategory,
+    defaultLang,
+  } = parseOptions;
+
+  const search = params.toString();
+
+  const parsed = useMemo(
+    () =>
+      parseSearchState(new URLSearchParams(search), {
+        defaultType,
+        ...(defaultQ !== undefined ? { defaultQ } : {}),
+        ...(defaultSort !== undefined ? { defaultSort } : {}),
+        ...(defaultLimit !== undefined ? { defaultLimit } : {}),
+        ...(defaultCategory !== undefined ? { defaultCategory } : {}),
+        ...(defaultLang !== undefined ? { defaultLang } : {}),
+      }),
+    [search, defaultType, defaultQ, defaultSort, defaultLimit, defaultCategory, defaultLang]
+  );
+
+  const commit = useCallback(
+    (next: SearchQueryState, options?: { readonly replace?: boolean }): void => {
+      setParams(writeSearchState(next, new URLSearchParams(search)), options);
+    },
+    [setParams, search]
+  );
+
+  const bag = useMemo<SearchStateBag>(() => {
+    const state = parsed.state;
+    const apply = (
+      next: SearchQueryState,
+      options?: { readonly replace?: boolean }
+    ): void => {
+      commit(next, options);
+    };
+    return {
+      state,
+      issues: parsed.issues,
+      activeFilters: activeFilterCount(state),
+
+      // Typing replaces rather than pushes: one history entry per letter
+      // would make Back useless, which is the control the spec's acceptance
+      // leans on for "Back removes the last filter".
+      setText: (q) => apply(patchSearchState(state, { q }), { replace: true }),
+      setSort: (sort) => apply(patchSearchState(state, { sort })),
+      setCategory: (category) => apply(patchSearchState(state, { category })),
+      setLanguage: (lang) => apply(patchSearchState(state, { lang })),
+      toggleFilter: (slug, value) => apply(toggleFilterValue(state, slug, value)),
+      setFilter: (slug, values) => apply(setFilterValues(state, slug, values)),
+      setRange: (slug, range) => apply(setRangeValue(state, slug, range)),
+      setGeo: (geo) => apply(patchSearchState(state, { geo })),
+      // A page size is a preference, not a step through the results.
+      setLimit: (limit) => apply(patchSearchState(state, { limit }), { replace: true }),
+      clearAll: () => apply(clearFilters(state)),
+      goToAnchor: (anchor, direction) =>
+        apply(patchSearchState(state, { anchor, direction })),
+      patch: (patch) => apply(patchSearchState(state, patch)),
+    };
+  }, [parsed, commit]);
+
+  return <StateContext.Provider value={bag}>{children}</StateContext.Provider>;
+}
+
+/**
+ * The search state and its mutators. Throws when used outside
+ * `<SearchStateProvider>` — a control that silently rendered with an empty
+ * state would look like a search with no filters rather than a wiring bug.
+ */
+export function useSearchState(): SearchStateBag {
+  const bag = useContext(StateContext);
+  if (bag === null) {
+    throw new Error(
+      "useSearchState must be used inside <SearchStateProvider> — the URL is the state, and there is no fallback copy of it."
+    );
+  }
+  return bag;
+}

package/src/i18n/errorsMap.ts

@@ -0,0 +1,50 @@
+/**
+ * The pair's error map (frontend-standard §4 checklist #7, frontend-core
+ * §2.5): the generated `code → { status, params, remediation, en }` catalog
+ * plus a tiny `explain()` lookup. Backs the manifest `errors` block and gives
+ * hosts a mechanical UX branch beside `t(code, params)`. The map itself is
+ * generated from the backend registry (`pnpm gen:errors`); this file only
+ * adds the lookup helper and re-exports the public surface.
+ */
+import { SEARCH_ERRORS } from "./generated/errors.gen.js";
+import type { Remediation } from "./generated/errors.gen.js";
+
+export {
+  SEARCH_ERRORS,
+  SEARCH_ERROR_CODES,
+  searchErrorBundleEn,
+} from "./generated/errors.gen.js";
+export type {
+  SearchErrorCode,
+  SearchErrorSpec,
+  Remediation,
+} from "./generated/errors.gen.js";
+
+/**
+ * The window refusal, named because a skin MUST branch on it.
+ *
+ * `error.400.search_window_exceeded` means "you have paged past
+ * `MAX_RESULT_WINDOW`", and its `params.window` carries the depth. Rendered as
+ * an empty result page it reads as "there is nothing here", which is false and
+ * is the exact substitution `matchList` exists to prevent — so it gets a
+ * constant rather than a string somebody retypes at each call site.
+ */
+export const SEARCH_WINDOW_EXCEEDED = "error.400.search_window_exceeded";
+
+/**
+ * The engine is down. Distinct from "no results" in the same way
+ * `LoadFailed` is distinct from an empty list — the views turn EVERY backend
+ * exception into this 503, so a client never has to guess whether a blank
+ * page meant an outage.
+ */
+export const SEARCH_BACKEND_UNAVAILABLE = "error.503.search_backend_unavailable";
+
+/**
+ * Resolve a backend error code to its remediation hint, or `undefined` for a
+ * code this module doesn't know (e.g. a cross-cutting `stapel.http.*`
+ * fallback). Zero guessing at runtime — a static lookup over the generated map.
+ */
+export function explainSearchError(code: string): Remediation | undefined {
+  return (SEARCH_ERRORS as Record<string, { remediation: Remediation }>)[code]
+    ?.remediation;
+}

package/src/i18n/es.ts

@@ -0,0 +1,110 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { searchErrorBundleEs } from "./generated/errors.es.gen.js";
+
+export { searchErrorBundleEs } from "./generated/errors.es.gen.js";
+
+/**
+ * Spanish bundle for search-react — the `@stapel/search-react/i18n/es`
+ * subpath, opt-in exactly like `ru`.
+ *
+ * PROVENANCE: the backend catalogue is `origin=seed:authored` and unreviewed;
+ * the pair-authored copy below is the same grade.
+ */
+export const searchI18nBundleEs: I18nDictionary = {
+  ...searchErrorBundleEs,
+
+  "search.error.unknown": "Algo falló en la búsqueda.",
+
+  "search.results.title": "Resultados",
+  "search.results.loading": "Buscando…",
+  "search.results.load_failed": "No pudimos ejecutar esta búsqueda.",
+  "search.results.empty": "No hay nada que coincida con esta búsqueda.",
+  "search.results.retry": "Reintentar",
+  "search.results.count_approximate": "Unos {count} resultados",
+  "search.results.count_exact": "{count} resultados",
+  "search.results.took_ms": "{ms} ms",
+  "search.results.next": "Página siguiente",
+  "search.results.prev": "Página anterior",
+  "search.results.blocked.at_end": "Esta es la última página",
+  "search.results.blocked.at_start": "Esta es la primera página",
+  "search.results.window_exceeded":
+    "Esta página está más allá de lo que la búsqueda puede recorrer. Acota la búsqueda en lugar de seguir paginando.",
+  "search.results.promoted": "Promocionado",
+  "search.results.promoted_hint":
+    "Esta posición está pagada. Se marca porque la ley lo exige y no cambia lo que son los demás resultados.",
+  "search.results.distance_km": "a {km} km",
+  "search.results.untitled": "Sin título",
+  "search.results.open": "Abrir",
+
+  "search.sort.label": "Orden",
+  "search.sort.relevance": "Más relevantes",
+  "search.sort.newest": "Más recientes",
+  "search.sort.price_asc": "Precio: de menor a mayor",
+  "search.sort.price_desc": "Precio: de mayor a menor",
+  "search.sort.distance": "Más cercanos",
+  "search.sort.server_chose": "Ordenado por {sort}",
+
+  "search.facets.title": "Filtros",
+  "search.facets.loading": "Cargando filtros…",
+  "search.facets.load_failed": "No pudimos cargar los filtros.",
+  "search.facets.empty": "Esta búsqueda no ofrece filtros.",
+  "search.facets.clear": "Quitar",
+  "search.facets.clear_all": "Quitar todos los filtros ({count})",
+  "search.facets.approximate":
+    "Los recuentos son aproximados: había demasiados candidatos para contarlos todos.",
+  "search.facets.skipped":
+    "Estos filtros no se contaron para esta búsqueda: {slugs}",
+  "search.facets.not_counted": "sin contar",
+  "search.facets.drill_down_hint":
+    "Cada recuento es lo que obtendrías eligiendo ese valor en lugar del actual.",
+  "search.facets.range_from": "Desde",
+  "search.facets.range_to": "Hasta",
+  "search.facets.range_apply": "Aplicar",
+
+  "search.geo.title": "Ubicación",
+  "search.geo.radius_km": "A menos de {km} km",
+  "search.geo.clear": "En cualquier lugar",
+  "search.geo.box": "Dentro del área mostrada",
+  "search.geo.center": "Cerca de {lat}, {lon}",
+
+  "search.url.issues_title": "Parte de este enlace no se pudo leer",
+  "search.url.issue.not_a_number": "{param} no es un número y se ignoró",
+  "search.url.issue.geo_incomplete":
+    "la ubicación necesita lat y lon, así que se ignoró",
+  "search.url.issue.bbox_malformed":
+    "el área necesita cuatro números (minLat,minLon,maxLat,maxLon) y se ignoró",
+  "search.url.issue.range_malformed":
+    "{param} no es un rango from..to y se ignoró",
+
+  "search.degraded.title": "Lo que esta búsqueda no pudo hacer",
+  "search.degraded.typo_tolerance":
+    "No se corrigieron erratas: el motor de búsqueda configurado no puede hacerlo.",
+  "search.degraded.phrase_synonyms":
+    "No se ampliaron sinónimos: el motor de búsqueda configurado no puede hacerlo.",
+  "search.degraded.exact_total": "El número de resultados es una estimación.",
+  "search.degraded.exact_facet_counts": "Los recuentos de filtros son aproximados.",
+  "search.degraded.category_rollup":
+    "Pueden faltar subcategorías en estos resultados: el servicio de categorías no respondió.",
+  "search.degraded.scorer":
+    "El parámetro de ranking «{scorer}» no se aplicó: el motor configurado no puede evaluarlo.",
+  "search.degraded.unknown":
+    "La búsqueda informó de una limitación para la que esta página no tiene texto: {raw}",
+
+  "search.ranking.title": "Cómo se ordenan estos resultados",
+  "search.ranking.intro":
+    "Estos son los parámetros que determinan el orden de los resultados, con su peso relativo.",
+  "search.ranking.loading": "Cargando la información de ranking…",
+  "search.ranking.load_failed": "No pudimos cargar la información de ranking.",
+  "search.ranking.empty": "Esta instalación no declara parámetros de ranking.",
+  "search.ranking.parameter": "Parámetro",
+  "search.ranking.weight": "Peso",
+  "search.ranking.applies_to": "Se aplica a",
+  "search.ranking.inactive": "No aplicado: {reason}",
+  "search.ranking.notes": "Notas",
+  "search.ranking.link": "Cómo se ordenan estos resultados",
+};
+
+/** Register the es bundle. Call AFTER `registerSearchI18n`. */
+export function registerSearchI18nEs(engine: I18nEngine): void {
+  engine.registerBundle("es", searchI18nBundleEs);
+}

package/src/i18n/generated/errors.es.gen.ts

@@ -0,0 +1,69 @@
+// AUTO-GENERATED by scripts/gen-errors.mjs — do not edit by hand.
+// Source: stapel-auth canonical errors.json (backend codegen artifact).
+// Regenerate: pnpm gen:errors   ·   Drift gate: pnpm gen:errors:check
+// Locale source: backend translations/errors.es.json (locale catalog
+// beside the canonical errors.json — i18n-shipping.md §1).
+import type { SearchErrorCode } from "./errors.gen.js";
+
+/**
+ * `es` texts for every backend error code — complete over the registry by
+ * construction (the generator fails on a gap; the Record type fails compilation
+ * on drift). Import from the pair's `./i18n/es` subpath, NOT the main
+ * entry, so the locale stays out of hosts that don't ship it.
+ */
+export const searchErrorBundleEs: Record<SearchErrorCode, string> = {
+  "error.400.bad_request": "Solicitud incorrecta",
+  "error.400.captcha_invalid": "La verificación del captcha ha fallado. Inténtalo de nuevo.",
+  "error.400.captcha_required": "Se requiere el token del captcha.",
+  "error.400.expected_list": "Se esperaba una lista de elementos",
+  "error.400.field.blank": "{field} no puede estar vacío",
+  "error.400.field.does_not_exist": "{field} no existe",
+  "error.400.field.invalid": "{field} no es válido",
+  "error.400.field.invalid_choice": "{field} no es una opción válida",
+  "error.400.field.max_length": "{field} debe tener como máximo {max_length} caracteres",
+  "error.400.field.max_value": "{field} debe ser como máximo {max_value}",
+  "error.400.field.min_length": "{field} debe tener al menos {min_length} caracteres",
+  "error.400.field.min_value": "{field} debe ser como mínimo {min_value}",
+  "error.400.field.null": "{field} no puede ser nulo",
+  "error.400.field.required": "{field} es obligatorio",
+  "error.400.field.unique": "{field} debe ser único",
+  "error.400.invalid_ad_id": "ID de anuncio no válido",
+  "error.400.search_bad_cursor": "El cursor de paginación no es válido",
+  "error.400.search_bad_geo": "Filtro geográfico incorrecto: {reason}",
+  "error.400.search_bad_range": "El filtro de rango «{slug}» es incorrecto: {reason}",
+  "error.400.search_query_too_long": "El texto de búsqueda es demasiado largo",
+  "error.400.search_sort_needs_center": "Ordenar por distancia requiere lat y lon",
+  "error.400.search_too_many_facets": "Demasiados filtros de faceta (límite {limit})",
+  "error.400.search_too_many_ranges": "Demasiados filtros de rango (límite {limit})",
+  "error.400.search_unknown_doc_type": "Tipo de búsqueda desconocido «{doc_type}»",
+  "error.400.search_unknown_sort": "Orden desconocido «{sort}»",
+  "error.400.search_window_exceeded": "Esta página de resultados supera el límite de {window}. Acote la búsqueda en lugar de avanzar más páginas.",
+  "error.400.validation_error": "Error de validación",
+  "error.400.verification_failed": "La verificación ha fallado",
+  "error.400.verification_invalid_factor": "Este factor de verificación no está disponible",
+  "error.401.unauthorized": "Se requiere autenticación",
+  "error.402.payment_required": "Se requiere pago",
+  "error.403.forbidden": "No tienes permiso para realizar esta acción",
+  "error.403.network_blocked": "No se permiten solicitudes desde esta red.",
+  "error.403.search_forbidden": "No puede administrar el índice de búsqueda",
+  "error.403.verification_enrollment_required": "Es necesario registrar un factor de verificación.",
+  "error.403.verification_required": "Se requiere verificación adicional",
+  "error.404.ad_not_found": "Anuncio no encontrado",
+  "error.404.not_found": "Recurso solicitado no encontrado",
+  "error.404.verification_challenge_not_found": "Desafío de verificación no encontrado o caducado",
+  "error.405.method_not_allowed": "Método no permitido",
+  "error.406.not_acceptable": "No aceptable",
+  "error.408.request_timeout": "Tiempo de espera de la solicitud agotado",
+  "error.409.conflict": "El recurso ya existe",
+  "error.410.gone": "El recurso se ha eliminado permanentemente",
+  "error.413.payload_too_large": "El cuerpo de la solicitud es demasiado grande",
+  "error.415.unsupported_media_type": "Tipo de contenido no compatible",
+  "error.422.unprocessable_entity": "Entidad no procesable",
+  "error.423.locked": "El recurso está bloqueado",
+  "error.423.verification_locked": "Demasiados intentos fallidos — verificación bloqueada",
+  "error.429.rate_limit": "Demasiados intentos. Inténtalo de nuevo en {retry_after_minutes} minutos.",
+  "error.429.too_many_requests": "Demasiadas solicitudes. Inténtalo de nuevo más tarde.",
+  "error.500.internal": "Algo salió mal",
+  "error.503.mandate_unavailable": "No se puede verificar el mandato del espacio de trabajo",
+  "error.503.search_backend_unavailable": "El motor de búsqueda no está disponible",
+};