Skip to main content
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:
PropertyTypeDescription
statusnumberHTTP status code
errorAPIErrorBodyStructured error body
error.typestringMachine-readable error slug (e.g., not_found)
error.titlestringHuman-readable title
error.detailstringDetailed error message
request_idstringUnique ID for this request (include in support tickets)
headersHeadersFull 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 TypeRetried?
ConnectionErrorYes
TimeoutErrorYes
RateLimitError (429)Yes (after retry_after delay)
InternalServerError (5xx)Yes
BadRequestError (400)No
AuthenticationError (401)No
NotFoundError (404)No
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