Resilience Patterns

Network failures, rate limits, and transient server errors are facts of life in distributed systems. This guide covers patterns for handling them gracefully when integrating with the Signa API.

Transient vs. Permanent Failures

Before retrying, determine whether the failure is recoverable.

Status Code	Type	Action
`429`	Transient	Rate limited. Retry after the `Retry-After` header value.
`500`	Transient	Internal server error. Retry with exponential backoff.
`502`	Transient	Bad gateway. Retry with backoff (typically resolves within seconds).
`503`	Transient	Service temporarily unavailable. Retry with longer backoff.
`504`	Transient	Gateway timeout. Retry with backoff.
`400`	Permanent	Validation error. Fix the request payload before resending.
`401`	Permanent	Invalid or expired API key. Check your credentials.
`403`	Permanent	Insufficient scopes. Update your API key permissions.
`404`	Permanent	Resource not found. Verify the ID is correct.
`409`	Permanent	Conflict (e.g., duplicate create). Inspect the error body.
`410`	Permanent	Entity was merged. Follow the `merged_into` in the response.
`422`	Permanent	Semantic error. The request is well-formed but cannot be processed.

Only retry on transient failures (4xx rate limits and 5xx server errors). Retrying permanent failures wastes your rate limit budget and will never succeed.

Exponential Backoff with Jitter

The standard retry strategy for transient errors. Each retry waits longer than the previous one, with random jitter to avoid thundering-herd problems when many clients retry simultaneously. Algorithm:

delay = min(max_delay, base_delay * 2^attempt) + random(0, jitter)

TypeScript

interface RetryOptions {
  maxRetries?: number;
  baseDelayMs?: number;
  maxDelayMs?: number;
}

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  { maxRetries = 3, baseDelayMs = 1000, maxDelayMs = 60_000 }: RetryOptions = {}
): Promise<Response> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    // Do not retry permanent failures
    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
      return response;
    }

    // Success, return immediately
    if (response.ok) {
      return response;
    }

    // All retries exhausted
    if (attempt === maxRetries) {
      return response;
    }

    // Calculate delay
    let delayMs: number;

    if (response.status === 429) {
      // Prefer the server's Retry-After value
      const retryAfter = response.headers.get('Retry-After');
      delayMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : baseDelayMs * 2 ** attempt;
    } else {
      delayMs = baseDelayMs * 2 ** attempt;
    }

    // Cap at max delay, add jitter
    delayMs = Math.min(delayMs, maxDelayMs);
    delayMs += Math.random() * baseDelayMs;

    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  // Unreachable, but satisfies TypeScript
  throw new Error('Retry loop exited unexpectedly');
}

Retry Backoff Schedule

With the default settings (base_delay=1s, max_retries=3), the schedule looks like this:

Attempt	Base Delay	With Jitter (approx.)	Cumulative Wait
1	1 s	1.0 to 2.0 s	~1.5 s
2	2 s	2.0 to 3.0 s	~4 s
3	4 s	4.0 to 5.0 s	~8.5 s

For 429 responses, the Retry-After header overrides the calculated base delay. Always respect this value.

The Signa TypeScript SDK (@signa-so/sdk) has built-in retry logic with these defaults. If you are using the SDK, you get this behavior automatically.

Bulk Operation Retry

POST /v1/trademarks/batch does not return a per-item success or error status. A requested ID either resolves into the data array (as a full trademark) or, if it does not match anything, into the not_found array. There is no partial-item failure to retry inside a single batch call, since a lookup either finds a record or it does not. What can still fail is the request as a whole: a 429 if you are over your rate limit, or a 5xx if the API is having trouble. In that case, retry the whole batch with the standard backoff strategy from the section above:

TypeScript

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

const signa = new Signa({ api_key: 'sig_YOUR_KEY' });

async function fetchBatchWithRetry(ids: string[], maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const result = await signa.trademarks.batch({ ids });
      if (result.not_found.length > 0) {
        console.warn('Not found:', result.not_found);
      }
      return result.data;
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = 1000 * 2 ** attempt + Math.random() * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
  throw new Error('Retry loop exited unexpectedly');
}

See Bulk Operations for chunking large ID lists across multiple batch calls and staying under your rate limit while doing it.

Circuit Breaker Pattern

For high-throughput integrations, wrap your API calls in a circuit breaker to stop sending requests when the API is consistently failing. This protects both your application and the API from cascading failures. The circuit has three states:

Closed (normal): Requests flow through. Failures are counted.
Open (tripped): All requests fail immediately without contacting the API.
Half-open (probing): A single test request is sent. If it succeeds, the circuit closes; if it fails, it re-opens.

class CircuitBreaker {
  private state: 'closed' | 'open' | 'half-open' = 'closed';
  private failureCount = 0;
  private lastFailureTime = 0;

  constructor(
    private readonly failureThreshold: number = 5,
    private readonly resetTimeoutMs: number = 30_000
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      // Check if enough time has passed to try again
      if (Date.now() - this.lastFailureTime >= this.resetTimeoutMs) {
        this.state = 'half-open';
      } else {
        throw new Error('Circuit breaker is open, request blocked');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess(): void {
    this.failureCount = 0;
    this.state = 'closed';
  }

  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();

    if (this.failureCount >= this.failureThreshold) {
      this.state = 'open';
    }
  }
}

// Usage
const breaker = new CircuitBreaker(5, 30_000);

async function getTrademarkSafe(id: string) {
  return breaker.execute(() =>
    fetchWithRetry(`https://api.signa.so/v1/trademarks/${id}`, {
      headers: { Authorization: 'Bearer sig_YOUR_KEY' },
    })
  );
}

A circuit breaker should wrap your retry logic, not replace it. The retry function handles transient blips; the circuit breaker prevents sustained outages from overwhelming your application.

Request Timeouts

Always set explicit timeouts on API calls. A reasonable default for Signa endpoints:

Endpoint Type	Recommended Timeout
Single resource (`GET /v1/trademarks/:id`)	10 s
List / search (`GET` or `POST /v1/trademarks`)	15 s
Batch (`POST /v1/trademarks/batch`)	30 s

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10_000);

try {
  const response = await fetch('https://api.signa.so/v1/trademarks/tm_abc123', {
    headers: { Authorization: 'Bearer sig_YOUR_KEY' },
    signal: controller.signal,
  });
} finally {
  clearTimeout(timeout);
}

curl --max-time 10 https://api.signa.so/v1/trademarks/tm_abc123 \
  -H "Authorization: Bearer sig_YOUR_KEY"

Idempotent Requests

Mutation endpoints (PATCH, DELETE, and non-exempt POST, see Exempt Endpoints) require an Idempotency-Key header. This guarantees that if a request is retried, whether because of a network timeout, a dropped connection, or an ambiguous failure, the operation only executes once.

curl -X PATCH https://api.signa.so/v1/organization/api-keys/key_abc123 \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rename-prod-key-001" \
  -d '{"name": "Production key (renamed)"}'

How It Works

On the first request with a given key, the API processes the request normally and caches the response.
If the same key is sent again with the same request body, the API returns the cached response without re-executing the operation. Replays carry an Idempotent-Replayed: true response header and preserve the original request_id (in the body and on x-request-id), so you can tell a cached replay from a fresh execution.
If the same key is sent with a different body, the API returns 409 conflict, each key is bound to a specific request body.
If the same key is sent while the first request is still in flight, the API returns 409 idempotency_processing, wait for the original to complete, then retry with the same key to get its cached result.

Cached responses are stored for 24 hours, after which the key can be reused.

Only successful (2xx) responses are cached. Client errors (4xx) and server errors (5xx) are never cached, so if a request fails, you can safely retry with the same idempotency key without being pinned to the error.

Key Format

1-255 characters
Alphanumeric, dashes, and underscores only ([a-zA-Z0-9_-])
Must be unique per operation, use UUIDs, request identifiers, or a deterministic string derived from the operation (e.g., create-api-key-{name}-{timestamp})

Exempt Endpoints

Read-shaped POST endpoints are exempt by design from the Idempotency-Key requirement. They exist as POSTs only because their query bodies are too large or complex for a URL, and they create nothing. Sending a key is harmless (the value’s format is still validated, a malformed key returns 400 even here), but the middleware will not enforce or replay it.

Endpoint	Why exempt
`POST /v1/trademarks`	Read-only search, inherently safe to retry
`POST /v1/trademarks/batch`	Read-only batch lookup, inherently safe to retry
`POST /v1/suggest` (and other `/suggest` endpoints)	Read-only, inherently safe to retry
`POST /v1/reconcile`	Read-only diff against register data, creates nothing
`POST /v1/deadlines/compute`	Read-only computation, creates nothing
`POST /v1/watches/preview`	Dry-run match count, creates nothing
`POST /v1/alerts/lookup`	Bulk read by IDs (polling pattern), creates nothing

POST /v1/organization/api-keys and POST /v1/organization/api-keys/{id}/rotate are not exempt, even though they return one-time secrets. Idempotency replay is exactly what you want there: a retry with the same key returns the same secret instead of minting a second credential. The cached secret is only ever served to the caller that supplied the original Idempotency-Key.

Every other mutating endpoint (PATCH, DELETE, and any non-exempt POST) requires Idempotency-Key and will return 400 validation_error if it is missing.

Example: Safe Retry Pattern

The example below demonstrates a retry loop against PATCH /v1/organization/api-keys/{id} (renaming a key), which is enforced by the idempotency middleware.

TypeScript

import { randomUUID } from 'crypto';

async function renameApiKeySafe(keyId: string, name: string, maxRetries = 2): Promise<any> {
  const idempotencyKey = randomUUID();

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(`https://api.signa.so/v1/organization/api-keys/${keyId}`, {
        method: 'PATCH',
        headers: {
          'Authorization': `Bearer ${process.env.SIGNA_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify({ name }),
      });

      if (response.ok) return response.json();
      if (response.status < 500) return response.json(); // permanent error
    } catch {
      if (attempt === maxRetries) throw new Error('Request failed after retries');
    }

    await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
  }
}

The Signa TypeScript SDK sets the Idempotency-Key header automatically on all mutation requests. If you are using the SDK, you get idempotent retries without any extra code.

Decision Tree

Use this to determine the right strategy for any failure:

Request failed
  |
  |--> Status 400/401/403/404/410/422?
  |      --> Permanent failure. Do not retry. Log and handle.
  |
  |--> Status 409 (idempotency conflict)?
  |      --> Same key, different body. Use a new Idempotency-Key.
  |
  |--> Status 429?
  |      --> Read Retry-After header.
  |      --> Wait and retry with backoff.
  |
  |--> Status 500/502/503/504?
  |      --> Retry with exponential backoff + jitter.
  |      --> If 3+ consecutive 5xx: trip circuit breaker.
  |
  |--> Network error / timeout?
         --> Retry with backoff.
         --> If persistent: trip circuit breaker.

Getting started

Core concepts

Build with AI

Data

Monitoring

Working with the API

Use cases

Transient vs. Permanent Failures

Exponential Backoff with Jitter

Retry Backoff Schedule

Bulk Operation Retry

Circuit Breaker Pattern

Request Timeouts

Idempotent Requests

How It Works

Key Format

Exempt Endpoints

Example: Safe Retry Pattern

Decision Tree

​Transient vs. Permanent Failures

​Exponential Backoff with Jitter

​Retry Backoff Schedule

​Bulk Operation Retry

​Circuit Breaker Pattern

​Request Timeouts

​Idempotent Requests

​How It Works

​Key Format

​Exempt Endpoints

​Example: Safe Retry Pattern

​Decision Tree

Transient vs. Permanent Failures

Exponential Backoff with Jitter

Retry Backoff Schedule

Bulk Operation Retry

Circuit Breaker Pattern

Request Timeouts

Idempotent Requests

How It Works

Key Format

Exempt Endpoints

Example: Safe Retry Pattern

Decision Tree