Error Handling

Error (native)
└── NodeStashError           — Base SDK error (network, timeout)
    └── ApiError             — API returned an error response
        ├── AuthenticationError  — 401 (invalid/missing key)
        ├── NotFoundError        — 404 (resource not found)
        ├── ValidationError      — 400/422 (validation failed)
        └── RateLimitError       — 429 (rate limited)

import {
  NodeStash,
  NodeStashError,
  ApiError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
} from '@nodestash/sdk'

const client = new NodeStash({ apiKey: 'nds_live_...' })

try {
  const contact = await client.contacts.create({
    email: 'jane@acme.com',
    first_name: 'Jane',
  })
} catch (error) {
  if (error instanceof ValidationError) {
    // Field-level validation errors
    console.log('Validation failed:', error.message)
    for (const detail of error.details) {
      console.log(`  ${detail.field}: ${detail.message}`)
    }
  } else if (error instanceof AuthenticationError) {
    // Invalid or expired API key
    console.log('Authentication failed:', error.message)
  } else if (error instanceof NotFoundError) {
    // Resource doesn't exist
    console.log('Not found:', error.message)
  } else if (error instanceof RateLimitError) {
    // All retries exhausted
    console.log(`Rate limited. Retry after ${error.retryAfter}s`)
  } else if (error instanceof ApiError) {
    // Catch-all for other API errors
    console.log(`API error ${error.statusCode}: ${error.code}`)
  } else if (error instanceof NodeStashError) {
    // Network errors, timeouts
    console.log('SDK error:', error.message)
  }
}

interface ErrorDetail {
  field?: string
  message: string
}

const client = new NodeStash({
  apiKey: 'nds_live_...',
  maxRetries: 5,     // default: 3
  timeout: 60_000,   // default: 30_000ms
})

async function getContactOrNull(id: string) {
  try {
    return await client.contacts.get(id)
  } catch (error) {
    if (error instanceof NotFoundError) {
      return null
    }
    throw error
  }
}

const contact = await getContactOrNull('ct_maybe_exists')

async function createOrGetContact(email: string, name: string) {
  try {
    return await client.contacts.create({
      email,
      first_name: name,
    })
  } catch (error) {
    if (error instanceof ApiError && error.code === 'CONFLICT') {
      // Contact with this email already exists — find it
      const { data } = await client.contacts.list({ email })
      return data[0]
    }
    throw error
  }
}

try {
  await client.contacts.update('ct_abc123', { email: 'new@email.com' })
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error [${error.requestId}]: ${error.code} — ${error.message}`)
    // Share this request ID with support for debugging
  }
}