Nippy API Platform

COOLDOWN_ACTIVE

Cause: The user spun recently and the campaign cooldown is still active.Fix: Call getState() and show nextEligibleAt.

if (error.code === NippyErrorCodes.COOLDOWN_ACTIVE) {
  const state = await nippy.getState({ userId, campaignId })
  return { reason: 'cooldown', nextEligibleAt: state.nextEligibleAt }
}

SPIN_LIMIT_REACHED

Cause: The user used all allowed spins for the campaign.Fix: Disable the spin action and show the current state.

if (error.code === NippyErrorCodes.SPIN_LIMIT_REACHED) {
  return { reason: 'spin_limit_reached' }
}

CAMPAIGN_NOT_FOUND

Cause: The campaignId does not exist, belongs to another business, or the campaign is inactive.Fix: Verify the campaign ID and status before exposing it in your app.

if (error.code === NippyErrorCodes.CAMPAIGN_NOT_FOUND) {
  return { reason: 'campaign_unavailable' }
}

ALREADY_CLAIMED

Cause: claim() was called for a prize that was already claimed.Fix: Treat it as idempotent and show the already-claimed prize.

if (error.code === NippyErrorCodes.ALREADY_CLAIMED) {
  return { reason: 'already_claimed' }
}

RESERVATION_EXPIRED

Cause: The user did not claim the prize before the reservation expired.Fix: Inform the user that time ran out and call getState() again.

if (error.code === NippyErrorCodes.RESERVATION_EXPIRED) {
  const state = await nippy.getState({ userId, campaignId })
  return { reason: 'reservation_expired', state }
}

UNAUTHORIZED

Cause: The API key is missing or invalid.Fix: Check NIPPY_API_KEY and confirm it uses the correct prefix.

if (error.code === NippyErrorCodes.UNAUTHORIZED) {
  logger.error('Invalid Nippy API key')
}

FORBIDDEN

Cause: The API key does not have access to the requested resource.Fix: Check permissions and resource ownership in the console.

if (error.code === NippyErrorCodes.FORBIDDEN) {
  logger.error('Nippy key does not have access to this resource')
}

INVALID_PARAMETERS

Cause: Required fields are missing or a value has the wrong format.Fix: Validate data before calling the SDK.

if (error.code === NippyErrorCodes.INVALID_PARAMETERS) {
  return { reason: 'invalid_request' }
}

SERVER_ERROR

Cause: Nippy returned a 5xx error after automatic retries.Fix: Log traceId, show a generic state, and retry later.

if (error.code === NippyErrorCodes.SERVER_ERROR) {
  logger.error('Nippy server error', { traceId: error.traceId })
  return { reason: 'temporary_error' }
}

Start here

SDK

MCP

Error handling

Base pattern

Error codes

NippyError properties

​Base pattern

​Error codes

​NippyError properties

Base pattern

Error codes

NippyError properties