Error Handling (SDK)

The SDK throws typed error classes for different failure scenarios.

Error Classes

Class	When
TanqoryAPIError	Any non-2xx API response (400, 404, 422, 500, etc.)
TanqoryRateLimitError	429 Too Many Requests (extends TanqoryAPIError)
TanqoryNetworkError	Network failure, DNS, timeout
TanqoryAuthError	401 after token refresh failed (extends TanqoryAPIError)

Basic Error Handling

import {
  TanqoryAPIError,
  TanqoryRateLimitError,
  TanqoryNetworkError,
  TanqoryAuthError,
} from '@tanqory/sdk'

try {
  const product = await tanqory.products.create(storeId, data)
} catch (error) {
  if (error instanceof TanqoryAuthError) {
    // Token expired and refresh failed — redirect to login
    redirectToLogin()
  } else if (error instanceof TanqoryRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`)
    console.log(`Limit: ${error.limit}`)
    console.log(`Reset: ${error.resetAt}`)  // Date object
  } else if (error instanceof TanqoryAPIError) {
    console.log(error.statusCode)  // 400, 404, 422, etc.
    console.log(error.code)        // 'VALIDATION_ERROR', 'RESOURCE_NOT_FOUND', etc.
    console.log(error.message)     // 'Product title is required'
    console.log(error.details)     // Field-level errors (if validation)
  } else if (error instanceof TanqoryNetworkError) {
    console.log('Network error:', error.message)
  }
}

TanqoryAPIError Properties

Property	Type	Description
statusCode	number	HTTP status code
message	string	Human-readable error message
code	string	Machine-readable error code
details	array	Field-level validation errors (optional)
requestId	string	Unique request ID for support

TanqoryRateLimitError Properties

Extends TanqoryAPIError with:

Property	Type	Description
retryAfter	number	Seconds to wait before retrying
limit	number	Max requests per window
remaining	number	Requests remaining (always 0)
resetAt	Date	When the rate limit window resets

Auto-Retry

The SDK automatically retries on 429 and 5xx errors with exponential backoff:

const tanqory = createClient({
  apiKey: 'pk_live_...',
  maxRetries: 3,  // Default: 3. Set to 0 to disable.
})

Retry behavior:

• 429: Waits for Retry-After header value, then retries.
• 500, 502, 503, 504: Retries with exponential backoff (1s, 2s, 4s).
• 400, 401, 403, 404, 422: Not retried (client errors).

Disable Auto-Retry

const tanqory = createClient({
  apiKey: 'pk_live_...',
  maxRetries: 0,  // All errors throw immediately
})

Validation Error Details

When the API returns 422, the details array contains field-level errors:

try {
  await tanqory.products.create(storeId, { price: -100 })
} catch (error) {
  if (error instanceof TanqoryAPIError && error.details) {
    for (const detail of error.details) {
      console.log(`${detail.field}: ${detail.message}`)
      // "title: Product title is required"
      // "price: Price must be a positive number"
    }
  }
}

React Error Handling

With hooks, errors are available on the query/mutation result:

import { useProducts } from '@tanqory/sdk/react'
import { TanqoryAPIError } from '@tanqory/sdk'

function ProductList({ storeId }: { storeId: string }) {
  const { data, error } = useProducts(storeId)

  if (error instanceof TanqoryAPIError) {
    return <div>API Error: {error.message} ({error.code})</div>
  }

  return <div>{data?.data.map(p => <div key={p.id}>{p.title}</div>)}</div>
}