Errors and reliability

All SDK-specific errors extend NirmosError.

NirmosError
├── ConfigurationError
├── APIError
│   ├── AuthenticationError
│   ├── PermissionDeniedError
│   ├── NotFoundError
│   ├── ConflictError
│   ├── ValidationError
│   ├── RateLimitError
│   └── ServerError
├── TimeoutError
├── RequestAbortedError
├── NetworkError
├── StreamError
└── PromptRenderError

API errors

import { APIError } from "@nirmos/sdk";

try {
  await nirmos.gateway.chat.create(params);
} catch (error) {
  if (error instanceof APIError) {
    logger.error({
      status: error.status,
      code: error.code,
      requestId: error.requestId,
      traceId: error.traceId,
      retryable: error.retryable,
      retryAfterMs: error.retryAfterMs,
    });
  }
  throw error;
}

details can contain sanitized validation information. Do not depend on undocumented detail fields for core application control flow.

Rate limits

import { RateLimitError } from "@nirmos/sdk";

try {
  await nirmos.gateway.chat.create(params);
} catch (error) {
  if (error instanceof RateLimitError) {
    const delay = error.retryAfterMs ?? 1_000;
    // Queue or reschedule work according to the application's retry budget.
  }
}

Avoid unbounded retries. Apply a maximum attempt count, elapsed-time budget, and workload-specific fallback behavior.

Timeouts and cancellation

Set a client default and override it for individual calls:

const nirmos = new Nirmos({
  apiKey: process.env.NIRMOS_API_KEY!,
  timeoutMs: 30_000,
});

await nirmos.gateway.chat.create(params, {
  timeoutMs: 10_000,
});

Pass timeoutMs: 0 to disable the SDK timeout for one request. Prefer an explicit upper bound in production.

Application cancellation uses AbortSignal:

await nirmos.gateway.chat.create(params, {
  signal: request.signal,
});

Timeouts raise TimeoutError; caller cancellation raises RequestAbortedError.

Retry policy

The SDK retries safe GET requests for network failures, HTTP 408, 429, and 5xx responses. Default retry count is two.

Mutations and generation requests are not retried automatically because a failed connection does not prove the server did not execute the request. If an endpoint supports idempotency, provide an idempotency key:

await nirmos.prompts.create(params, {
  idempotencyKey: crypto.randomUUID(),
  maxRetries: 2,
});

Retries honor Retry-After when present.

Prompt rendering errors

PromptRenderError occurs locally before a gateway request:

import { PromptRenderError } from "@nirmos/sdk";

try {
  await nirmos.prompts.render(prompt, variables);
} catch (error) {
  if (error instanceof PromptRenderError) {
    console.error(error.missingVariables);
  }
}

Request metadata

Store request IDs on both success and error paths. They connect application logs to Nirmos traces without exposing provider internals.