Error Handling

import { ApiError, AuthenticationError, RetryExhaustedError } from "@keystoneos/sdk";

try {
  await client.settlements.get("non-existent-id");
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status);   // 404
    console.log(error.message);  // "Settlement not found"
    console.log(error.body);     // Raw response body
    console.log(error.headers);  // Response headers
  } else if (error instanceof AuthenticationError) {
    // M2M credentials invalid or Auth0 unavailable
    console.log(error.message);
  } else if (error instanceof RetryExhaustedError) {
    // All retries failed (429 or 5xx)
    console.log(error.lastStatus); // 503
    console.log(error.attempts);   // 3
  }
}

const key = client.generateIdempotencyKey();

// If this fails mid-request (network error), retrying with the same key
// returns the existing resource instead of creating a duplicate
const settlement = await client.settlements.create({
  idempotencyKey: key,
  // ...
});

try {
  await client.settlements.list();
} catch (error) {
  if (error instanceof RetryExhaustedError && error.lastStatus === 429) {
    // All retries exhausted on rate limit
    // Wait longer and retry, or queue for later
  }
}

try {
  await client.settlements.submitComplianceDecision(id, { decision: "approve" });
} catch (error) {
  if (error instanceof ApiError && error.status === 409) {
    // Settlement is no longer in COMPLIANCE_CHECKING state
    // Fetch current state and act accordingly
    const settlement = await client.settlements.get(id);
    console.log(`Current state: ${settlement.state}`);
  }
}