Error Handling

All SDK errors throw AISecSDKException with a typed errorType property. Transport failures also carry facts that callers can use without parsing the message:

Property	Meaning
failureKind	'http' when AIRS returned a response; 'network' when fetch rejected
statusCode	Actual HTTP response status; absent for network failures
retryAfterMs	Valid server retry guidance normalized to milliseconds

Configuration and response-validation errors leave these transport fields undefined. The metadata does not contain credentials, request payloads, URLs, authorization headers, or raw response bodies.

Error Types

ErrorType	Value	When
SERVER_SIDE_ERROR	AISEC_SERVER_SIDE_ERROR	5xx responses from the API
CLIENT_SIDE_ERROR	AISEC_CLIENT_SIDE_ERROR	4xx responses / network failures
USER_REQUEST_PAYLOAD_ERROR	AISEC_USER_REQUEST_PAYLOAD_ERROR	Invalid input (bad UUID, oversized content)
MISSING_VARIABLE	AISEC_MISSING_VARIABLE	Missing required config (API key, client ID)
AISEC_SDK_ERROR	AISEC_SDK_ERROR	Internal SDK errors
OAUTH_ERROR	AISEC_OAUTH_ERROR	OAuth2 token fetch failures
RESPONSE_VALIDATION	AISEC_RESPONSE_VALIDATION	2xx response body failed Zod validation or JSON parsing

Usage

import { AISecSDKException, ErrorType } from '@cdot65/prisma-airs-sdk';

try {
  await scanner.asyncScan(batch, { numRetries: 0 });
} catch (err) {
  if (err instanceof AISecSDKException) {
    if (err.failureKind === 'http' && err.statusCode === 429) {
      console.error(`Rate limited; server delay is ${err.retryAfterMs ?? 'unspecified'}ms`);
      return;
    }
    if (err.failureKind === 'network') {
      console.error('Network failure; an async POST may have reached AIRS:', err.message);
      return;
    }

    switch (err.errorType) {
      case ErrorType.SERVER_SIDE_ERROR:
        console.error('Server error — retry later:', err.message);
        break;
      case ErrorType.CLIENT_SIDE_ERROR:
        console.error('Bad request:', err.message);
        break;
      case ErrorType.USER_REQUEST_PAYLOAD_ERROR:
        console.error('Invalid input:', err.message);
        break;
      case ErrorType.MISSING_VARIABLE:
        console.error('Missing config:', err.message);
        break;
      case ErrorType.OAUTH_ERROR:
        console.error('Auth failed:', err.message);
        break;
      case ErrorType.RESPONSE_VALIDATION:
        console.error('API response shape changed:', err.message);
        break;
    }
  }
}

Retry Behavior

The SDK automatically retries on transient errors:

• Status codes: 500, 502, 503, 504
• Network failures: Retried within the same retry budget
• 429: Not retried automatically; valid Retry-After header guidance takes precedence over the AIRS JSON retry_after.interval / unit fields and is exposed as retryAfterMs
• Backoff: Exponential with full jitter (uniform [0, 2^attempt × 1000ms])
• Max retries: Configurable 0-5, default 5
• Scanner per-call override: Pass { numRetries } to any Scanner operation; 0 means one total fetch attempt, and an omitted value preserves the global setting
• 401/403 handling: Management/Model Security/Red Team clients automatically refresh the OAuth token and retry once on 401 or 403 responses

For async POSTs, a terminal network error or 5xx response is an ambiguous outcome: AIRS may have accepted the request. The SDK does not claim exactly-once submission and does not expose a generic retryable flag because retry safety depends on the operation. Polling GETs are idempotent; async submission is not known to be.