Error Handling

Both SDKs use typed error classes that extend a base OptropicError. Every error includes a machine-readable code, HTTP status, and human-readable message.

Error Hierarchy

OptropicError
├── AuthenticationError      (401 — invalid or expired API key)
├── ForbiddenError           (403 — insufficient permissions)  [Python only]
├── NotFoundError            (404 — resource not found)        [Python only]
├── ValidationError          (400 — invalid request body)      [Python only]
├── InvalidSerialError       (400 — malformed serial)
├── InvalidGTINError         (400 — malformed GTIN)
├── InvalidCodeError         (400 — malformed code format)
├── CodeNotFoundError        (404 — serial not found)
├── BatchNotFoundError       (404 — batch not found)
├── RevokedCodeError         (410 — asset revoked)
├── RateLimitedError         (429 — rate limit exceeded)
├── QuotaExceededError       (429 — monthly quota reached)
├── NetworkError             (0   — connection failed)
├── TimeoutError             (0   — request timed out)
└── ServiceUnavailableError  (503 — server temporarily down)

Catching Errors

TypeScript

import { OptropicError, RateLimitedError, AuthenticationError } from 'optropic';

try {
  const asset = await client.assets.verify('SER-invalid');
} catch (err) {
  if (err instanceof RateLimitedError) {
    // Back off and retry
    console.log(`Rate limited. Retry after: ${err.message}`);
  } else if (err instanceof AuthenticationError) {
    // Check API key
    console.error('Invalid API key');
  } else if (err instanceof OptropicError) {
    // All other API errors
    console.error(`[${err.code}] ${err.message} (HTTP ${err.status})`);
  } else {
    throw err; // Not an Optropic error
  }
}

Python

from optropic import OptropicError, RateLimitError, AuthenticationError

try:
    asset = client.assets.verify("SER-invalid")
except RateLimitError as e:
    print(f"Rate limited. {e.message}")
except AuthenticationError as e:
    print("Invalid API key")
except OptropicError as e:
    print(f"[{e.code}] {e.message} (HTTP {e.status})")

Automatic Retries

The SDK automatically retries on transient errors (429, 500, 502, 503, 504) using exponential backoff with jitter:

delay = min(base_delay × 2^attempt, max_delay) + (delay × 0.5 × random())

Default configuration: 3 retries, 1s base delay, 10s max delay. This prevents thundering herd effects when multiple clients retry simultaneously.

Idempotency

POST, PUT, and PATCH requests automatically include an Idempotency-Key header (UUID v4). This means retries are safe — the server deduplicates requests with the same idempotency key. GET and DELETE requests do not include this header.