Error Handling

Result pattern, retryable errors, and checkout error codes.

const result = await client.catalogue.getProducts()

if (!result.ok) {
  console.error(result.error.code)       // 'NETWORK_ERROR', 'NOT_FOUND', etc.
  console.error(result.error.message)    // human-readable message
  console.error(result.error.retryable)  // boolean
  console.error(result.error.suggestion) // optional fix hint
  console.error(result.error.docs_url)   // optional link to docs
  return
}

console.log(result.value.items)

Result Pattern

Every SDK method returns a discriminated union. Always check result.ok before accessing result.value.

type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: CimplifyError }

type CimplifyError = {
  code: string
  message: string
  retryable: boolean
  suggestion?: string
  docs_url?: string
}

CimplifyError Fields

Field	Type	Description
`code`	`string`	Machine-readable error code
`message`	`string`	Human-readable description
`retryable`	`boolean`	Whether the operation can be retried
`suggestion`	`string?`	Suggested fix for the developer
`docs_url`	`string?`	Link to relevant documentation

Retry Helper

Check retryable and use exponential backoff. Max 3 attempts is a good default.

async function withRetry<T>(
  fn: () => Promise<Result<T>>,
  maxAttempts = 3,
): Promise<Result<T>> {
  let lastResult: Result<T>

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    lastResult = await fn()
    if (lastResult.ok) return lastResult
    if (!lastResult.error.retryable) return lastResult

    // Exponential backoff: 1s, 2s, 4s
    await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)))
  }

  return lastResult!
}

// Usage
const result = await withRetry(() => client.catalogue.getProducts({ limit: 10 }))

Common Checkout Error Codes

Code	Recoverable	Description
`ALREADY_PROCESSING`	No	A checkout is already in progress for this cart
`PAYMENT_FAILED`	Yes	Payment provider declined the transaction
`TIMEOUT`	Yes	Checkout timed out waiting for payment confirmation
`AUTH_INCOMPLETE`	Yes	Customer must complete authentication before checkout
`AUTH_LOST`	Yes	Session expired during checkout
`CANCELLED`	Yes	Checkout was aborted by the customer
`INVALID_CART`	No	Cart is empty or invalid
`NETWORK_ERROR`	Yes	Connection failure during checkout

See /reference/error-codes for the full list of error codes across all services.

Branching on Error Codes

const result = await client.cart.addItem({ item_id: 'prod_xxxxx', quantity: 1 })

if (!result.ok) {
  switch (result.error.code) {
    case 'ITEM_UNAVAILABLE':
      showToast('This item is no longer available')
      break
    case 'OUT_OF_STOCK':
      showToast('This item is out of stock')
      break
    case 'NETWORK_ERROR':
      if (result.error.retryable) showToast('Connection issue. Try again.')
      break
    default:
      showToast(result.error.message)
  }
}