Cargando documentación…
Cargando documentación…
@notheadless/sdk
Todos los errores llegan como una única clase NubeError con un code tipado. Las búsquedas que no encuentran nada devuelven null en lugar de lanzar un error.
import { NubeError, isNubeError } from "@notheadless/sdk"
try {
await nube.checkouts.create({ lineItems, couponCode })
} catch (e) {
if (isNubeError(e, "coupon_rejected")) return showCouponError()
if (isNubeError(e) && e.retryable) return retryLater(e.retryAfter)
throw e
}| Prop | Tipo | Descripción |
|---|---|---|
| invalid_request / invalid_fields | 400 | Query mal formada. Con selects tipados, invalid_fields no puede pasar. |
| unauthorized | 401 | Token inválido. No hay fallback sin token. |
| store_forbidden | 403 | El token pertenece a otra tienda, o la tienda no está habilitada. |
| resource_not_found | 404 | findUnique devuelve null. …OrThrow lanza este error. |
| checkout_rejected / coupon_rejected | 422 | El core de Tiendanube rechazó los ítems o el cupón. |
| rate_limit_exceeded | 429 | Se reintenta automáticamente usando Retry-After. |
| upstream_error / upstream_unavailable / upstream_timeout | 502–504 | Los GET se reintentan con backoff. |
| network_error / timeout | 0 | Falló el fetch o se cumplió timeoutMs. |
La spec OpenAPI de Storefront describe los recursos como objetos libres, así que los modelos del SDK se derivan de respuestas reales. Para que sigan siendo fieles, cada fila de producto y de categoría se valida en runtime contra el modelo, incluidas las formas anidadas de variantes, imágenes y categorías de las que depende la lógica de commerce.
createClient({ schema: "warn" }) // por defecto: loguea cada drift distinto una sola vez
createClient({ schema: "throw" }) // falla rápido: contract tests, CI
createClient({ onSchemaIssue: (i) => Sentry.captureMessage(`drift ${i.resource}.${i.path}`, { extra: i }) })
// [@notheadless/sdk] schema drift: product.variants[].price expected string|null, received numberUn contract test en vivo (npm run test:contract) selecciona todos los campos de todos los modelos contra la API real con schema: "throw". Correlo de forma programada para enterarte de los cambios de la API antes que tus compradores.
| Prop | Tipo | Descripción |
|---|---|---|
| Sin token | Headers de la respuesta | Disponible solo donde la API permite acceso sin token. |
| Con token | Headers de la respuesta | Requests a nivel tienda. Consultá el límite actual y el saldo que te queda. |
| Token + IP del comprador | Headers de la respuesta | Requests a nivel comprador. Usá withBuyerIp() o getBuyerIp con una fuente de IP confiable. |
El batching y la deduplicación son tu principal defensa: una página de listado de productos suele resolverse en 1–2 requests. Los últimos headers X-RateLimit-* quedan expuestos en nube.rateLimit.