Error Handling

Robust error handling is essential for building reliable applications with the Narrative SDK. This guide covers common error types and patterns for handling them.

Prerequisites

SDK installed and configured (see SDK Quickstart)

Error types

HTTP errors

The SDK throws errors for HTTP response codes indicating failures:

Status	Name	Description
400	Bad Request	Invalid request parameters or malformed query
401	Unauthorized	Invalid or missing API key
403	Forbidden	API key lacks required permissions
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
502	Bad Gateway	Upstream service error
503	Service Unavailable	Service temporarily unavailable

Network errors

Connection issues throw standard JavaScript errors:

Connection timeout
DNS resolution failure
Network unreachable

Validation errors

Query or data validation failures return detailed error messages:

NQL syntax errors
Schema validation failures
Invalid parameter values

Basic error handling

Wrap SDK calls in try-catch blocks:

import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
});

try {
  const datasets = await api.getDatasets();
  console.log('Datasets:', datasets.records.length);
} catch (error) {
  console.error('Error fetching datasets:', error);
}

Handling specific errors

Check the error status for specific handling:

try {
  const dataset = await api.getDataset(12345);
  console.log('Dataset:', dataset.name);
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed: Check your API key');
  } else if (error.status === 403) {
    console.error('Permission denied: API key lacks access to this dataset');
  } else if (error.status === 404) {
    console.error('Dataset not found');
  } else if (error.status === 429) {
    console.error('Rate limited: Too many requests');
  } else if (error.status >= 500) {
    console.error('Server error: Try again later');
  } else {
    console.error('Unexpected error:', error);
  }
}

Rate limiting

Handle rate limits with exponential backoff:

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 5,
  baseDelayMs = 1000
): Promise<T> {
  let lastError: Error | undefined;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error as Error;

      // Only retry on rate limits and server errors
      const status = (error as any).status;
      if (status !== 429 && status < 500) {
        throw error;
      }

      if (attempt < maxRetries - 1) {
        const delay = baseDelayMs * Math.pow(2, attempt);
        const jitter = Math.random() * 1000;
        console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay + jitter));
      }
    }
  }

  throw lastError;
}

// Usage
const datasets = await withRetry(() => api.getDatasets());

Query error handling

NQL queries can fail for various reasons:

try {
  const result = await api.executeNql({
    nql: 'SELECT user_id, email, created_at FROM company_data."my_dataset" LIMIT 10',
    data_plane_id: null,
  });

  if (result.state === 'failed') {
    console.error('Query failed:', result.failures);
  } else {
    console.log('Query completed:', result.result.rows, 'rows');
  }
} catch (error) {
  if (error.status === 400) {
    // Parse error details for NQL syntax issues
    console.error('Invalid query:', error.message);
  } else {
    console.error('Query error:', error);
  }
}

Validating before execution

Catch syntax errors before running expensive queries:

async function safeExecuteQuery(nql: string) {
  // First validate the query
  try {
    await api.validateNql({ nql, data_plane_id: null });
  } catch (validationError) {
    console.error('Query validation failed:', validationError);
    throw new Error('Invalid query syntax');
  }

  // Then execute
  return await api.executeNql({ nql, data_plane_id: null });
}

Creating an error wrapper

Build a reusable error handler:

class NarrativeError extends Error {
  status?: number;
  details?: unknown;

  constructor(message: string, status?: number, details?: unknown) {
    super(message);
    this.name = 'NarrativeError';
    this.status = status;
    this.details = details;
  }

  isRetryable(): boolean {
    return this.status === 429 || (this.status ?? 0) >= 500;
  }

  isAuthError(): boolean {
    return this.status === 401 || this.status === 403;
  }

  isNotFound(): boolean {
    return this.status === 404;
  }
}

async function wrapApiCall<T>(operation: () => Promise<T>): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    const status = (error as any).status;
    const message = (error as any).message || 'Unknown error';
    throw new NarrativeError(message, status, error);
  }
}

// Usage
try {
  const dataset = await wrapApiCall(() => api.getDataset(12345));
} catch (error) {
  if (error instanceof NarrativeError) {
    if (error.isAuthError()) {
      console.error('Authentication issue');
    } else if (error.isNotFound()) {
      console.error('Resource not found');
    } else if (error.isRetryable()) {
      console.error('Temporary error, retry later');
    }
  }
}

Logging errors

Implement structured error logging:

function logError(context: string, error: unknown) {
  const errorInfo = {
    timestamp: new Date().toISOString(),
    context,
    message: (error as Error).message,
    status: (error as any).status,
    stack: (error as Error).stack,
  };

  console.error(JSON.stringify(errorInfo, null, 2));

  // Send to your logging service
  // await logService.error(errorInfo);
}

try {
  const datasets = await api.getDatasets();
} catch (error) {
  logError('getDatasets', error);
  throw error;
}

Graceful degradation

Provide fallbacks when services are unavailable:

async function getDatasetsWithFallback() {
  try {
    const response = await api.getDatasets();
    return { source: 'api', data: response.records };
  } catch (error) {
    const status = (error as any).status;

    if (status >= 500 || status === 429) {
      // Return cached data if available
      const cachedData = await getCachedDatasets();
      if (cachedData) {
        console.warn('Using cached datasets due to API error');
        return { source: 'cache', data: cachedData };
      }
    }

    throw error;
  }
}

Best practices

Practice	Description
Always use try-catch	Wrap all SDK calls in error handlers
Check error status	Handle different errors appropriately
Implement retries	Use exponential backoff for transient errors
Validate inputs	Catch errors early with validation
Log errors	Record errors for debugging and monitoring
Graceful degradation	Provide fallbacks when possible

Troubleshooting

Issue	Cause	Solution
Frequent 401 errors	API key expired or invalid	Generate a new API key
Frequent 429 errors	Too many requests	Implement rate limiting and backoff
Intermittent 500 errors	Server issues	Implement retry logic
Network timeouts	Slow connection or large responses	Increase timeout or paginate

Authentication

Configure authentication properly

API Keys

Manage API keys and permissions

Tracking Jobs

Handle async operation errors

SDK Reference

Complete SDK documentation

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

Error types

HTTP errors

Network errors

Validation errors

Basic error handling

Handling specific errors

Rate limiting

Query error handling

Validating before execution

Creating an error wrapper

Logging errors

Graceful degradation

Best practices

Troubleshooting

Authentication

API Keys

Tracking Jobs

SDK Reference

​Prerequisites

​Error types

​HTTP errors

​Network errors

​Validation errors

​Basic error handling

​Handling specific errors

​Rate limiting

​Query error handling

​Validating before execution

​Creating an error wrapper

​Logging errors

​Graceful degradation

​Best practices

​Troubleshooting

​Related content

Authentication

API Keys

Tracking Jobs

SDK Reference

Prerequisites

Error types

HTTP errors

Network errors

Validation errors

Basic error handling

Handling specific errors

Rate limiting

Query error handling

Validating before execution

Creating an error wrapper

Logging errors

Graceful degradation

Best practices

Troubleshooting

Related content