Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.signa.so/llms.txt

Use this file to discover all available pages before exploring further.

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