Errors, Retries, and Idempotency

Error Types You Should Expect

Validation errors are normalized to 422 in the API handler.

SDK Error Handling

Use SDK helpers to avoid manual try/catch branching:

import { safe, isDefinedError } from '@session-services/sdk';

const [error, result] = await safe(client.order.get({ id: 'ord_01jps5cgsfgve5b5g2666kyryh' }));

if (isDefinedError(error)) {
  // API-defined error with code/message/data
}

Retry Guidance

• Do retry: transient network errors, 429, and most 5xx.
• Do not retry blindly: 400, 401, 403, 404, 422.
• Use exponential backoff with jitter for retriable failures.

Idempotency for Financial Operations

Programmatic refunds support idempotencyKey to prevent duplicate processing:

await client.order.refund({
  id: 'ord_01jps5cgsfgve5b5g2666kyryh',
  fullRefund: true,
  reason: 'CUSTOMER_REQUEST',
  idempotencyKey: 'refund_ord_01jps5cgsfgve5b5g2666kyryh_2026-02-12',
});

Use stable keys per logical action, not per request attempt.