The SDK uses a structured error hierarchy. All errors extend InfiniumError.

Error Hierarchy

InfiniumError
+-- AuthenticationError      (401/403)
+-- ValidationError          (field-specific)
+-- RateLimitError           (429)
+-- NetworkError             (connection failures)
|   +-- TimeoutError         (request timeouts)
+-- ServerError              (500+)
+-- NotFoundError            (404)
+-- BatchError               (batch operation failures)
+-- ConfigurationError       (invalid client config)
+-- PayloadTooLargeError     (413)

Catching Errors

import {
  InfiniumError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NetworkError,
  ServerError,
  TimeoutError,
  NotFoundError,
  BatchError,
  PayloadTooLargeError,
} from 'infinium-o2';

try {
  await client.sendTaskData(taskData);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Bad agentId or agentSecret
    console.error('Check your credentials');
  } else if (error instanceof ValidationError) {
    // Invalid input data
    console.error(`Field '${error.field}': ${error.message}`);
  } else if (error instanceof RateLimitError) {
    // Too many requests
    console.error(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof NotFoundError) {
    // Agent or resource not found
    console.error(`Resource not found: ${error.resource}`);
  } else if (error instanceof TimeoutError) {
    // Request timed out
    console.error('Request timed out');
  } else if (error instanceof NetworkError) {
    // Cannot reach the API
    console.error(`Network error: ${error.originalError?.message}`);
  } else if (error instanceof PayloadTooLargeError) {
    // Payload exceeds 1MB
    console.error(`Payload too large: ${error.actualSize} > ${error.maxSize}`);
  } else if (error instanceof ServerError) {
    // 5xx from the API (after retries exhausted)
    console.error('Server error -- try again later');
  } else if (error instanceof InfiniumError) {
    // Catch-all for any SDK error
    console.error('SDK error:', error.message);
  }
}

Error Details

All errors have these base properties:

Property	Type	Description
message	string	Human-readable error message
statusCode	number | undefined	HTTP status code (if applicable)
details	Record<string, unknown>	Additional context
name	string	Error class name
stack	string	Stack trace

All errors implement toJSON() for serialization.

AuthenticationError

Raised on HTTP 401 or 403.

ValidationError

Raised for invalid input data.

Property	Type	Description
field	string | undefined	Which field failed validation

RateLimitError

Raised on HTTP 429.

Property	Type	Description
retryAfter	number | undefined	Seconds to wait before retrying

NetworkError

Raised when the API is unreachable.

Property	Type	Description
originalError	Error | undefined	The underlying error

TimeoutError

Extends NetworkError. Raised when a request exceeds the configured timeout.

ServerError

Raised on HTTP 5xx after all retries are exhausted.

NotFoundError

Raised on HTTP 404.

Property	Type	Description
resource	string | undefined	Resource identifier

BatchError

Raised when a batch operation fails.

Property	Type	Description
failedTasks	number	Number of failed sends
totalTasks	number	Total tasks in batch
errors	string[] | undefined	Error messages

ConfigurationError

Raised for invalid client configuration.

Property	Type	Description
configField	string | undefined	Which config key is invalid

PayloadTooLargeError

Raised when the serialized payload exceeds 1 MB.

Property	Type	Description
maxSize	number | undefined	Maximum allowed size in bytes
actualSize	number | undefined	Actual payload size in bytes

---

Type Guards

import { isInfiniumError, isErrorType } from 'infinium-o2';

if (isInfiniumError(error)) {
  console.log(error.statusCode);
}

if (isErrorType(error, RateLimitError)) {
  console.log(error.retryAfter);
}

isInfiniumError(error: unknown): error is InfiniumError

Check if an error is any Infinium error.

isErrorType<T>(error: unknown, errorClass): error is T

Check if an error is a specific Infinium error type.

toInfiniumError(error: unknown): InfiniumError

Convert any error to an InfiniumError. Non-Infinium errors are wrapped.

---

Retry Behavior

The SDK automatically retries certain errors with exponential backoff:

Error Type	Auto-Retried?
ServerError (5xx)	Yes
NetworkError	Yes
TimeoutError	Yes
AuthenticationError (401/403)	No
ValidationError	No
RateLimitError (429)	No
NotFoundError (404)	No

Retry Configuration

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  maxRetries: 3,   // Number of retry attempts (default: 3)
  timeout: 30000,  // Per-request timeout in ms (default: 30000)
});

Backoff formula: min(1000 * 2^(attempt-1), 30000) with +/-25% jitter.

---

Rate Limiting

The SDK includes a built-in token bucket rate limiter:

const client = new InfiniumClient({
  agentId: '...',
  agentSecret: '...',
  enableRateLimiting: true,  // Enabled by default
  requestsPerSecond: 10,     // Default: 10 req/s
});

• Burst size defaults to 2x requestsPerSecond
• Automatically throttles requests to stay within the limit
• If the server returns 429, a RateLimitError is raised (not auto-retried)

---

Validation

The SDK validates data before sending:

Validation	Limit
name length	Max 500 characters
description length	Max 10,000 characters
String fields	Max 2,000 characters
Payload size	Max 1 MB
Duration	0 to 86,400 seconds (24 hours)
Path IDs (agentId, etc.)	Must be valid UUID format

Validation failures raise ValidationError with the offending field name.