Error classes

Every non-2xx response is parsed as an RFC 9457 application/problem+json envelope and thrown as a SonnyLabsError subclass. The fromProblem helper dispatches on the dot-namespaced code first (so auth.api_key.expired is always an AuthenticationError regardless of HTTP status remapping by intermediate proxies), then falls back to the HTTP status.

import {
  SonnyLabsError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from "@sonnylabs/sdk";

try {
  await client.createScan({
    kind: "content",
    surface: "user_message",
    content,
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // err.code is one of "auth.api_key.invalid" / "auth.api_key.revoked" / ...
  } else if (err instanceof RateLimitError) {
    // honour err.retryAfterSeconds
  } else if (err instanceof ValidationError) {
    for (const field of err.errors) {
      console.error(`${field.path}: ${field.code}`);
    }
  } else if (err instanceof SonnyLabsError) {
    // catch-all for any other Problem-shaped failure
  } else {
    throw err;
  }
}

SonnyLabsError

Base class for every typed SDK error. Carries the parsed Problem envelope plus convenience accessors.

AuthenticationError

Thrown for any code starting with auth. (or HTTP 401 envelopes without a recognised code). Surface a re-credential UI.

ScopeMissingError

Thrown when the API key authenticated but lacks the scope this endpoint demands (auth.scope.missing or HTTP 403). Mint a key with the required scope.

RateLimitError

Thrown on HTTP 429. Carries retryAfterSeconds parsed from the server's Retry-After header so callers driving their own retry loop can honour the server's hint.

IdempotencyConflictError

Thrown for any code starting with idempotency. or HTTP 409. The canonical case is reusing the same Idempotency-Key header with a different request body.

ValidationError

Thrown for any code starting with validation. or HTTP 422. The inherited errors array contains per-field ProblemFieldError entries.

NotFoundError

Thrown on HTTP 404. The requestId is preserved on the instance for correlating with server logs.

ServerError

Thrown for any 5xx response that isn't 503 (the SDK retries 503 internally before surfacing a ServerError). Treat as a permanent server-side failure for that request — silently retrying risks duplicating side effects.

fromProblem

Lower-level dispatch helper used internally by the client. Exposed in case you are building your own transport on top of the OpenAPI schema and want to reuse the same error mapping.

import { fromProblem } from "@sonnylabs/sdk";

throw fromProblem(
  problem,
  response.status,
  response.headers.get("x-request-id") ?? undefined,
);