Error handling

Entitlement denials are valid typed responses. Authentication, validation, network, service availability, and infrastructure rate-limit failures throw SDK errors.

import {
  AuthenticationError,
  RateLimitError,
  UsageyError,
  ValidationError,
} from "@usagey/sdk";

try {
  await usagey.track({
    externalId: "customer-42",
    feature: "api_requests",
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Retry according to the response guidance.
  } else if (error instanceof AuthenticationError) {
    // Verify the key and selected environment.
  } else if (error instanceof ValidationError) {
    // Correct the request before retrying.
  } else if (error instanceof UsageyError) {
    // Handle another Usagey API or transport failure.
  }
}

Do not retry validation or authentication failures without changing the request. For retryable operations, retain the same idempotency key.