Error Handling

Error types, automatic retries, and rate limit handling

The SDK provides typed error classes for every error scenario, automatic retries for transient failures, and structured error bodies that match the API’s RFC 9457-inspired format.

Error Hierarchy

All errors extend SignaError. API errors (4xx/5xx) extend SignaAPIError. Network issues have their own classes.

SignaError                   ← base (client-side issues)
├── SignaAPIError             ← base for all API errors (4xx/5xx)
│   ├── BadRequestError       ← 400
│   ├── AuthenticationError   ← 401
│   ├── PermissionError       ← 403
│   ├── NotFoundError         ← 404
│   ├── ConflictError         ← 409
│   ├── RateLimitError        ← 429 (has retry_after)
│   └── InternalServerError   ← 5xx
├── ConnectionError           ← DNS, TCP, TLS failures
└── TimeoutError              ← request exceeded timeout

Catching Errors

Use instanceof to handle specific error types:

import { Signa } from '@signa-so/sdk';

try {
  const tm = await signa.trademarks.retrieve('tm_invalid');
} catch (err) {
  if (err instanceof Signa.NotFoundError) {
    console.log('Trademark not found');
  } else if (err instanceof Signa.RateLimitError) {
    console.log(`Rate limited — retry after ${err.retry_after}s`);
  } else if (err instanceof Signa.AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof Signa.SignaAPIError) {
    // Catch-all for other API errors
    console.log(`API error ${err.status}: ${err.message}`);
  } else if (err instanceof Signa.ConnectionError) {
    console.log('Network issue:', err.message);
  } else if (err instanceof Signa.TimeoutError) {
    console.log('Request timed out');
  }
}

Error Properties

Every SignaAPIError includes:

Property	Type	Description
status	number	HTTP status code
error	APIErrorBody	Structured error body
error.type	string	Machine-readable error slug (e.g., not_found)
error.title	string	Human-readable title
error.detail	string	Detailed error message
request_id	string	Unique ID for this request (include in support tickets)
headers	Headers	Full response headers

try {
  await signa.trademarks.list({ offices: ['invalid_office'] });
} catch (err) {
  if (err instanceof Signa.BadRequestError) {
    console.log(err.error.type);    // "validation_error"
    console.log(err.error.detail);  // "Invalid office code: invalid_office"
    console.log(err.request_id);    // "req_abc123"
  }
}

Automatic Retries

The SDK automatically retries requests that fail due to transient issues:

Error Type	Retried?
ConnectionError	Yes
TimeoutError	Yes
RateLimitError (429)	Yes (after retry_after delay)
InternalServerError (5xx)	Yes — unless the error body says retryable: false
BadRequestError (400)	No
AuthenticationError (401)	No
NotFoundError (404)	No

Since SDK 0.4.0, an explicit retryable: false in the server’s error envelope overrides the status-based rule. Deterministic failures like the watch preview’s 504 preview_timeout are not retried, even though they are 5xx — a blind retry would re-run the exact same over-budget work. Narrow the query instead.

Retries use exponential backoff. Configure the maximum number of retries:

const signa = new Signa({
  api_key: process.env.SIGNA_API_KEY,
  max_retries: 3,  // default: 2
});

Set to 0 to disable automatic retries entirely.

Per-Request Override

Override retry behavior for a single request:

// No retries for this specific call
const tm = await signa.trademarks.retrieve('tm_abc123', undefined, {
  max_retries: 0,
});

// Extra retries for a critical batch operation
const result = await signa.trademarks.batch(
  { ids: ['tm_abc', 'tm_def'] },
  { max_retries: 5 },
);

Rate Limits

When you exceed the API’s rate limit, the SDK receives a 429 response and automatically retries after the Retry-After period. If retries are exhausted, a RateLimitError is thrown.

try {
  const results = await signa.trademarks.list({ offices: ['uspto'] });
} catch (err) {
  if (err instanceof Signa.RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retry_after} seconds.`);
    console.log(`Request ID: ${err.request_id}`);
  }
}

Timeouts

The default timeout is 30 seconds. Configure it globally or per-request:

// Global: 60 second timeout
const signa = new Signa({
  api_key: process.env.SIGNA_API_KEY,
  timeout: 60_000,
});

// Per-request: 10 second timeout
const tm = await signa.trademarks.retrieve('tm_abc123', undefined, {
  timeout: 10_000,
});

Debug Mode

Enable request/response logging to diagnose issues:

const signa = new Signa({
  api_key: process.env.SIGNA_API_KEY,
  debug: true,
});

// All requests will log method, URL, status, and timing to console