Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.nippy.la/llms.txt

Use this file to discover all available pages before exploring further.

El SDK lanza instancias de NippyError para errores operacionales. Usa NippyErrorCodes para manejar cada caso de forma explícita.
No muestres mensajes internos de error directamente al usuario. Registra error.code, error.status y error.traceId para diagnóstico.

​
Patrón base

import { NippyError, NippyErrorCodes } from '@nippy/sdk'

try {
  await nippy.spin({ userId, campaignId })
} catch (error) {
  if (!(error instanceof NippyError)) throw error

  console.error(error.code, error.message, error.traceId)
}

​
Códigos de error

Causa: El usuario giró recientemente y el cooldown de la campaña sigue activo.Solución: Consulta getState() y muestra nextEligibleAt.
if (error.code === NippyErrorCodes.COOLDOWN_ACTIVE) {
  const state = await nippy.getState({ userId, campaignId })
  return { reason: 'cooldown', nextEligibleAt: state.nextEligibleAt }
}
Causa: El usuario agotó sus spins permitidos en la campaña.Solución: Deshabilita el botón de girar y muestra el estado actual.
if (error.code === NippyErrorCodes.SPIN_LIMIT_REACHED) {
  return { reason: 'spin_limit_reached' }
}
Causa: El campaignId no existe, no pertenece al negocio o la campaña está inactiva.Solución: Verifica el ID de campaña y su estado antes de exponerla en tu app.
if (error.code === NippyErrorCodes.CAMPAIGN_NOT_FOUND) {
  return { reason: 'campaign_unavailable' }
}
Causa: Se llamó claim() para un premio que ya fue reclamado.Solución: Trata el caso como idempotente y muestra el premio ya reclamado.
if (error.code === NippyErrorCodes.ALREADY_CLAIMED) {
  return { reason: 'already_claimed' }
}
Causa: El usuario no reclamó el premio antes de la expiración de la reserva.Solución: Informa que el tiempo expiró y vuelve a consultar getState().
if (error.code === NippyErrorCodes.RESERVATION_EXPIRED) {
  const state = await nippy.getState({ userId, campaignId })
  return { reason: 'reservation_expired', state }
}
Causa: Falta la API key o la key es inválida.Solución: Revisa NIPPY_API_KEY y confirma que use el prefijo correcto.
if (error.code === NippyErrorCodes.UNAUTHORIZED) {
  logger.error('Invalid Nippy API key')
}
Causa: La API key no tiene acceso al recurso solicitado.Solución: Revisa permisos y pertenencia del recurso en la consola.
if (error.code === NippyErrorCodes.FORBIDDEN) {
  logger.error('Nippy key does not have access to this resource')
}
Causa: Faltan campos requeridos o algún valor tiene formato incorrecto.Solución: Valida los datos antes de llamar al SDK.
if (error.code === NippyErrorCodes.INVALID_PARAMETERS) {
  return { reason: 'invalid_request' }
}
Causa: Nippy respondió con un error 5xx después de los reintentos automáticos.Solución: Registra traceId, muestra un estado genérico y reintenta más tarde.
if (error.code === NippyErrorCodes.SERVER_ERROR) {
  logger.error('Nippy server error', { traceId: error.traceId })
  return { reason: 'temporary_error' }
}

​
Propiedades de NippyError

error.code      // string
error.message   // string
error.status    // number
error.traceId   // string | undefined