Errores

Todos los errores son RFC 9457 Problem Details, con Content-Type: application/problem+json. Sin wrapper error: {} ni details genérico.

Cada type resuelve a esta página: el slug final es el ancla de su sección, como #not-found-404.

La forma común

Seis campos, siempre presentes:

string

requerido

URI canónica y estable del tipo. Es el único campo que conviene comparar en código.

string

requerido

Texto estable por tipo. No describe la ocurrencia.

integer

requerido

El mismo código HTTP de la respuesta.

string

requerido

Describe esta ocurrencia. No lo parsees: no es una interfaz y puede cambiar sin aviso.

string

requerido

Alias corto en snake_case. Es un string abierto: pueden aparecer códigos nuevos sin romper un cliente viejo. El slug de type es el mismo código en kebab-case.

string

requerido

Identifica la ocurrencia y coincide con el header X-Request-ID. Es lo que va en un reporte de bug.

string

Opcional en RFC 9457, y la API no lo emite.

Todo error trae el header X-Request-ID. El 401 suma WWW-Authenticate: Bearer, y el 429, Retry-After.

El catálogo completo

`code`	Status	Slug de `type`	Extensiones propias
`invalid_request`	400	`invalid-request`	`errors[]`
`unauthorized`	401	`unauthorized`	—
`forbidden_connection`	403	`forbidden-connection`	—
`forbidden_scope`	403	`forbidden-scope`	—
`not_found`	404	`not-found`	—
`conflict`	409	`conflict`	—
`cart_items_limit_exceeded`	422	`cart-items-limit-exceeded`	`max_items_per_cart`, `actual_items`
`signal_batch_limit_exceeded`	422	`signal-batch-limit-exceeded`	`max_signals_per_batch`, `actual_signals`
`rate_limited`	429	`rate-limited`	— (header `Retry-After`)
`internal_error`	500	`internal-error`	—
`signals_unavailable`	503	`signals-unavailable`	—

Las extensiones van al nivel raíz del Problem, no anidadas.

`invalid_request` — 400

El cuerpo o los parámetros no cumplen el contrato: falta un campo requerido, sobra uno no declarado, o un valor no valida.

{
  "type": "https://api.crossup.ai/salespilot/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "request_id": "req_01J9ABC",
  "errors": [
    {
      "code": "missing_field",
      "detail": "context_item_id is required for surface pdp.",
      "pointer": "/context_item_id"
    }
  ]
}

array

requerido

Al menos un elemento, con code y detail obligatorios y un pointer opcional: un JSON Pointer RFC 6901 al campo culpable, que empieza con /. Con él marcás el input equivocado en vez de mostrar un texto genérico.

`unauthorized` — 401

No mandaste Authorization, o la clave que mandaste no vale. Es el mismo error para las dos causas: distinguirlas le diría a un atacante si una clave existe.

{
  "type": "https://api.crossup.ai/salespilot/errors/unauthorized",
  "title": "Authentication required",
  "status": 401,
  "detail": "The request did not include a valid bearer token.",
  "code": "unauthorized",
  "request_id": "req_01J9ABC"
}

Ver Claves y seguridad.

`forbidden_connection` — 403

La clave autenticó bien, pero el connection_id pedido no pertenece a esa tienda.

{
  "type": "https://api.crossup.ai/salespilot/errors/forbidden-connection",
  "title": "Connection is not accessible",
  "status": 403,
  "detail": "The connection is not accessible to the authenticated store.",
  "code": "forbidden_connection",
  "request_id": "req_01J9ABC"
}

Es 403 y no 404 porque la conexión viaja en el path: el cliente ya sabe que la pidió. Para recursos de catálogo es al revés: ver not_found.

`forbidden_scope` — 403

La clave autenticó bien, pero no tiene el scope de la operación: recommendations:read, catalog:read o signals:write. Una clave no cambia de scopes: hace falta otra que lo tenga.

{
  "type": "https://api.crossup.ai/salespilot/errors/forbidden-scope",
  "title": "Key is missing the required scope",
  "status": 403,
  "detail": "The key does not have the signals:write scope.",
  "code": "forbidden_scope",
  "request_id": "req_01J9ABC"
}

`not_found` — 404

El recurso no existe, o existe y es de otra tienda. Ningún detail dice cuál de los dos es.

{
  "type": "https://api.crossup.ai/salespilot/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found",
  "request_id": "req_01J9ABC"
}

Un 404 inesperado con una clave válida casi siempre es la clave de otra tienda, no un id mal escrito.

`conflict` — 409

El request choca con el estado actual: una regresión de source_version en la ingesta de catálogo. Una señal más vieja que la aplicada no pisa el catálogo.

{
  "type": "https://api.crossup.ai/salespilot/errors/conflict",
  "title": "Request conflicts with current state",
  "status": 409,
  "detail": "The signal source_version is older than the applied version.",
  "code": "conflict",
  "request_id": "req_01J9ABC"
}

No lo reintentes sin cambios: va a fallar igual. Es un error de orden de eventos, no uno transitorio.

`cart_items_limit_exceeded` — 422

El carrito de un pedido de recomendaciones supera el límite configurado.

{
  "type": "https://api.crossup.ai/salespilot/errors/cart-items-limit-exceeded",
  "title": "Cart item limit exceeded",
  "status": 422,
  "detail": "The cart exceeds the configured item limit.",
  "code": "cart_items_limit_exceeded",
  "request_id": "req_01J9ABC",
  "max_items_per_cart": 200,
  "actual_items": 512
}

integer

requerido

El límite vigente, 200 por defecto. Viene en la respuesta para que no lo hardcodees.

integer

requerido

Cuántos ítems mandaste.

`signal_batch_limit_exceeded` — 422

Un lote de señales del storefront trae más de las permitidas.

{
  "type": "https://api.crossup.ai/salespilot/errors/signal-batch-limit-exceeded",
  "title": "Signal batch limit exceeded",
  "status": 422,
  "detail": "The batch exceeds the signal limit.",
  "code": "signal_batch_limit_exceeded",
  "request_id": "req_01J9ABC",
  "max_signals_per_batch": 50,
  "actual_signals": 80
}

integer

requerido

El límite vigente, 50 por defecto. El SDK ya parte los lotes con este número.

integer

requerido

Cuántas señales mandaste.

`rate_limited` — 429

La clave gastó sus 60 pedidos por minuto; Retry-After dice cuántos segundos esperar. Ver Cuota y caché.

{
  "type": "https://api.crossup.ai/salespilot/errors/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "The key exceeded its request budget.",
  "code": "rate_limited",
  "request_id": "req_01J9ABC"
}

`internal_error` — 500

Algo se rompió del lado del servidor. El detail nunca trae el stack, el mensaje interno ni el nombre de un componente.

{
  "type": "https://api.crossup.ai/salespilot/errors/internal-error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected internal error occurred.",
  "code": "internal_error",
  "request_id": "req_01J9ABC"
}

Acá el request_id es imprescindible: conecta lo que viste con el log del servidor.

`signals_unavailable` — 503

El almacén de señales del storefront no está disponible. Es transitorio: reintentá con espera. El SDK lo hace solo, con el mismo signal_id, y un reintento nunca cuenta dos veces.

{
  "type": "https://api.crossup.ai/salespilot/errors/signals-unavailable",
  "title": "Signals cannot be recorded right now",
  "status": 503,
  "detail": "The signal store is unavailable.",
  "code": "signals_unavailable",
  "request_id": "req_01J9ABC"
}

Cómo manejarlos desde el SDK

El SDK traduce cualquiera de estos Problems a un CrossUpApiError tipado y preserva las extensiones que no conoce, para no romperse cuando la API sume campos.

import { isCrossUpApiError } from "@crossup/storefront";

try {
  await crossup.getCatalogItem("itm_demo_remera");
} catch (err) {
  if (isCrossUpApiError(err) && err.is("unauthorized", "forbidden_scope")) {
    console.log("revisá la clave ·", err.requestId);
  }
  throw err;
}

Usá isCrossUpApiError(err) y no err instanceof CrossUpApiError: instanceof falla si hay dos copias del paquete en el árbol de módulos.

Tres reglas del SDK para cuando algo sale mal de verdad:

No se mira el Content-Type, se mira la forma del cuerpo. Un proxy puede reescribir el header, y el error se tipa igual.
El status del transporte manda. Si el cuerpo declara otro, la diferencia queda en extensions.status: es la prueba de que algo en el medio reescribe respuestas.
errorFromResponse nunca lanza. Ante HTML, cuerpo vacío o JSON que no es un Problem devuelve un error sintético con code: "unexpected_response", el status real y el cuerpo crudo.

​La forma común

​El catálogo completo

​invalid_request — 400

​unauthorized — 401

​forbidden_connection — 403

​forbidden_scope — 403

​not_found — 404

​conflict — 409

​cart_items_limit_exceeded — 422

​signal_batch_limit_exceeded — 422

​rate_limited — 429

​internal_error — 500

​signals_unavailable — 503

​Cómo manejarlos desde el SDK

La forma común

El catálogo completo

`invalid_request` — 400

`unauthorized` — 401

`forbidden_connection` — 403

`forbidden_scope` — 403

`not_found` — 404

`conflict` — 409

`cart_items_limit_exceeded` — 422

`signal_batch_limit_exceeded` — 422

`rate_limited` — 429

`internal_error` — 500

`signals_unavailable` — 503

Cómo manejarlos desde el SDK