Error Handling

The NodeRails SDK throws typed errors that map to HTTP status codes and API error responses. All errors extend the base ApiError class.

Error hierarchy

Error class hierarchytext

Error
└── ApiError                    — Base: any API / HTTP error
    ├── AuthenticationError     — 401 Unauthorized
    ├── NotFoundError           — 404 Not Found
    ├── ValidationError         — 400 Bad Request
    └── RateLimitError          — 429 Too Many Requests

Error
├── ConnectionError             — Network / DNS failure
├── TimeoutError                — Request timed out
└── SignatureVerificationError  — Webhook HMAC mismatch

ApiError

Base class for all HTTP errors returned by the API.

Property	Type	Description
`message`	`string`	Human-readable error description
`status`	`number`	HTTP status code (e.g. 400, 401, 404)
`code`	`string \| undefined`	Machine-readable error code

Catching API errorstypescript

import { ApiError } from '@noderails/sdk';

try {
  const session = await noderails.checkoutSessions.create(params);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.message);  // "Validation failed"
    console.error(error.status);   // 400
    console.error(error.code);     // "VALIDATION_ERROR"
  }
}

AuthenticationError

Thrown when the API key is missing, invalid, or expired. Extends ApiError with status: 401.

Handle auth errorstypescript

import { AuthenticationError } from '@noderails/sdk';

try {
  const customers = await noderails.customers.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // API key is invalid — check your configuration
    console.error('Auth failed:', error.message);
  }
}

💡

Common causes

Using a public key (pk) instead of a secret key (sk)
API key was rotated or invalidated
Wrong environment (test key on live, or vice-versa)

NotFoundError

Thrown when the requested resource does not exist. Extends ApiError with status: 404.

Handle not foundtypescript

import { NotFoundError } from '@noderails/sdk';

try {
  const intent = await noderails.paymentIntents.retrieve('non-existent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Resource not found');
  }
}

ValidationError

Thrown when request parameters fail server-side validation. Extends ApiError with status: 400.

Handle validation errorstypescript

import { ValidationError } from '@noderails/sdk';

try {
  const session = await noderails.checkoutSessions.create({
    // missing required fields
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid params:', error.message);
  }
}

RateLimitError

Thrown when you exceed the API rate limit. Extends ApiError with status: 429.

Handle rate limitingtypescript

import { RateLimitError } from '@noderails/sdk';

try {
  const result = await noderails.paymentIntents.list();
} catch (error) {
  if (error instanceof RateLimitError) {
    // Back off and retry after a delay
    console.error('Rate limited — retry later');
  }
}

ConnectionError

Thrown when the SDK cannot reach the API server due to a network failure (DNS, connectivity, etc.). This is not an HTTP error, no response was received.

Handle connection errorstypescript

import { ConnectionError } from '@noderails/sdk';

try {
  const prices = await noderails.prices.convert({ from: 'USD', to: 'ETH', amount: '100' });
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('Network error:', error.message);
  }
}

TimeoutError

Thrown when the request exceeds the configured timeout (default 30 s).

Handle timeoutstypescript

import { TimeoutError } from '@noderails/sdk';

try {
  const session = await noderails.checkoutSessions.create(params);
} catch (error) {
  if (error instanceof TimeoutError) {
    console.error('Request timed out');
  }
}

SignatureVerificationError

Thrown by noderails.webhooks.constructEvent() when the webhook signature does not match the expected HMAC-SHA256 hash.

Handle signature errorstypescript

import { SignatureVerificationError } from '@noderails/sdk';

try {
  const event = noderails.webhooks.constructEvent(body, signature, secret);
} catch (error) {
  if (error instanceof SignatureVerificationError) {
    console.error('Invalid webhook signature');
    return res.status(400).send('Invalid signature');
  }
}

🚨

Security

Never ignore SignatureVerificationError in production. An invalid signature means the request may not have originated from NodeRails.

Best practices

Comprehensive error handlingtypescript

import {
  ApiError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ConnectionError,
  TimeoutError,
} from '@noderails/sdk';

async function createCheckout(params) {
  try {
    return await noderails.checkoutSessions.create(params);
  } catch (error) {
    if (error instanceof AuthenticationError) {
      // Log and alert — this is a config issue
      logger.fatal('API key invalid', error);
    } else if (error instanceof ValidationError) {
      // Return field errors to caller
      throw new BadRequestError(error.message);
    } else if (error instanceof NotFoundError) {
      throw new NotFoundError('Resource not found');
    } else if (error instanceof RateLimitError) {
      // Retry with exponential backoff
      return retry(() => noderails.checkoutSessions.create(params));
    } else if (error instanceof TimeoutError) {
      // Retry once
      return noderails.checkoutSessions.create(params);
    } else if (error instanceof ConnectionError) {
      // Network issue — retry or queue
      logger.error('Network failure', error);
    } else if (error instanceof ApiError) {
      // Catch-all for other HTTP errors
      logger.error(`API error ${error.status}: ${error.message}`);
    }
    throw error;
  }
}