Terminal49 SDK Error Handling

Catch and handle Terminal49 TypeScript SDK errors, including API validation failures and network timeouts, so your integration recovers gracefully.

The SDK throws typed errors you can catch and handle based on the error type.

Error types

Error	Cause
AuthenticationError	Invalid or missing API key
AuthorizationError	Valid API key but insufficient permissions
NotFoundError	Resource doesn’t exist or isn’t accessible
ValidationError	Invalid request parameters
RateLimitError	Too many requests
FeatureNotEnabledError	Feature is not enabled for the account, for example trade intelligence or routing data
UpstreamError	Carrier or terminal API is unavailable
Terminal49Error	Generic error fallback

Basic error handling

import {
  Terminal49Client,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
} from '@terminal49/sdk';

const client = new Terminal49Client({
  apiToken: process.env.T49_API_TOKEN!,
});

try {
  await client.containers.get('container-uuid');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Container not found');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retrying in 60s');
    await new Promise((resolve) => setTimeout(resolve, 60000));
  } else {
    throw error;
  }
}

Automatic retries

The SDK automatically retries 429 and 5xx responses with exponential backoff up to maxRetries (default: 2). Retries apply to reads: GET requests and the read-only POST queries under client.tradeIntel. Other writes are retried only when you send an Idempotency-Key header.

const client = new Terminal49Client({
  apiToken: process.env.T49_API_TOKEN!,
  maxRetries: 3,
});

Error properties

All SDK errors include:

Property	Type	Description
message	string	Human-readable error description
status	number	HTTP status code
details	unknown	Raw error payload from the API