Error Handling

The SDK throws typed errors that you can catch and handle specifically.

Error types

Error	When	Properties
`AuthenticationError`	Invalid or missing API key (401)	`statusCode`
`NotFoundError`	Invalid chain, endpoint, or resource (404)	`statusCode`
`RateLimitError`	Too many requests (429)	`statusCode`, `retryAfter`
`ValidationError`	Invalid parameters	`field`
`TimeoutError`	Request exceeded timeout	`timeout`
`NetworkError`	Connection failed	`cause`
`ApiError`	Other server errors (5xx)	`statusCode`, `body`

Catching errors


import {
  Spectrum,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  TimeoutError,
} from '@spectrum-nodes/sdk';
 
const spectrum = new Spectrum({ api: 'https://your-endpoint.simplystaking.xyz/YOUR_API_KEY/' });
 
try {
  const block = await spectrum.core.getBlockHeight('ethereum');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Bad API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}ms`);
  } else if (error instanceof NotFoundError) {
    console.error('Chain or endpoint not found');
  } else if (error instanceof ValidationError) {
    console.error(`Invalid param: ${error.field}`);
  } else if (error instanceof TimeoutError) {
    console.error(`Request timed out after ${error.timeout}ms`);
  } else {
    throw error;
  }
}

Retry behavior

The SDK automatically retries on:

Network errors (connection refused, DNS failures)
5xx server errors
429 rate limit errors (with backoff)

Retries use exponential backoff: 1s → 2s → 4s (configurable).

Not retried: 4xx client errors (except 429), validation errors, timeouts.


// Customize retry behavior
const spectrum = new Spectrum({
  api: 'https://your-endpoint.simplystaking.xyz/YOUR_API_KEY/',
  retry: {
    maxRetries: 5,
    baseDelay: 500,
    maxDelay: 15000,
  },
});
 
// Disable retries
const spectrum = new Spectrum({
  api: 'https://your-endpoint.simplystaking.xyz/YOUR_API_KEY/',
  retry: { maxRetries: 0 },
});

Error hook

Use the onError hook for centralized error logging:


const spectrum = new Spectrum({
  api: 'https://your-endpoint.simplystaking.xyz/YOUR_API_KEY/',
  hooks: {
    onError: (url, error) => {
      myLogger.error('Spectrum API error', {
        url,
        error: error.message,
        type: error.constructor.name,
      });
    },
  },
});