01 Software

Error Handling

Error handling guide

Error Handling

The SDK throws errors and provides type-safe error classes and type guards.

Error Types

Error ClassCodeDescription
NetworkErrorNETWORK_ERRORNetwork connection failure
ApiErrorAPI_ERRORHTTP error (includes status code)
ValidationErrorVALIDATION_ERRORData validation failure (400)
TimeoutErrorTIMEOUT_ERRORRequest timeout (408)
UsageLimitErrorUSAGE_LIMIT_ERRORMonthly API quota exceeded (429)
GoneErrorGONE_ERRORResource gone (410)
ServiceUnavailableErrorSERVICE_UNAVAILABLE_ERRORService unavailable (503, includes retryAfter)
ConfigErrorCONFIG_ERRORConfiguration error

All errors extend SDKError and provide getUserMessage() and a suggestion property.

Type Guards

import {
  isNetworkError,
  isApiError,
  isValidationError,
  isTimeoutError,
  isUsageLimitError,
  isGoneError,
  isServiceUnavailableError,
} from '@01.software/sdk'

try {
  const { docs } = await client.from('products').find()
} catch (error) {
  if (isNetworkError(error)) {
    // Network error
  } else if (isApiError(error)) {
    // API error (error.statusCode available)
  } else if (isValidationError(error)) {
    // Validation error
  } else if (isTimeoutError(error)) {
    // Timeout
  } else if (isUsageLimitError(error)) {
    // Monthly API quota exceeded (check usage via error.usage)
  } else if (isGoneError(error)) {
    // Resource gone (410)
  } else if (isServiceUnavailableError(error)) {
    // Service unavailable (check error.retryAfter for retry timing)
  }
}

React Query Error Handling

const { data, error, isError } = client.query.useQuery({
  collection: 'products',
  options: { limit: 10 },
})

if (isError) {
  return <div>{error.getUserMessage()}</div>
}

Retry Behavior

The SDK automatically retries requests internally.

  • Default max retries: 3
  • Retryable statuses: 408, 429, 500, 502, 503, 504
  • Non-retryable: 401, 403, 404, 422 (always fail immediately)
  • Delay: Math.min(1000 * 2^attempt, 10000) (1s → 2s → 4s)

Monthly API quota exceeded (429 + X-Usage-Limit header) is not retried and throws UsageLimitError immediately.

On this page