Production Reliability

This guide covers what you need to know to run Tabstack dependably in production: caching behavior, when to bypass it, retry handling, error patterns, and the operational decisions that matter at scale.

---

Caching

Tabstack caches extraction results by URL. When you request the same URL again, the API may return a cached result rather than re-fetching the page. This is usually what you want: it’s faster and reduces cost.

What’s cached: The response for a given URL + endpoint combination. Effort level and schema are also factors; changing them may produce a fresh fetch.

How long results are cached: Cache TTL is not publicly documented. For time-sensitive data (pricing, inventory, live stats), always set nocache: true.

When to use nocache: true:

• Pricing or availability data that changes frequently
• Pages you know have updated since your last fetch
• Debugging extraction issues (confirms the problem isn’t a stale cache)
• Any data with a business requirement for freshness

// Price monitoring — always fresh
const result = await client.extract.json({
  url: 'https://competitor.com/pricing',
  nocache: true,
  json_schema: { /* ... */ }
})

---

Automatic retries

The SDK automatically retries failed requests twice with exponential backoff. The following errors are retried:

Status	Error
408	Request Timeout
409	Conflict
429	Rate Limit
500+	Server errors
N/A	Network / connection failures

Retries happen transparently. You don’t need to implement retry logic for these cases.

Disable retries if you’re running your own retry orchestration:

const client = new Tabstack({
  apiKey: process.env.TABSTACK_API_KEY,
  maxRetries: 0
})

// Or per-request:
await client.extract.json({ url, json_schema }, { maxRetries: 5 })

---

Error handling patterns

Handle 422 explicitly

A 422 UnprocessableEntityError means the page was fetched but extraction failed. This is the most actionable error; you can often fix it:

import Tabstack, { UnprocessableEntityError } from '@tabstack/sdk'

try {
  return await client.extract.json({ url, json_schema })
} catch (err) {
  if (err instanceof UnprocessableEntityError) {
    // Try with full rendering
    return await client.extract.json({
      url,
      json_schema,
      effort: 'max',
      nocache: true
    })
  }
  throw err
}

Rate limit handling

429 errors are auto-retried, but if you’re hitting them consistently you’re exceeding your plan’s rate limit. Use exponential backoff in your own queuing layer for bulk operations:

import { RateLimitError } from '@tabstack/sdk'

async function extractWithBackoff(
  url: string,
  schema: object,
  attempt = 0
): Promise<unknown> {
  try {
    return await client.extract.json({ url, json_schema: schema })
  } catch (err) {
    if (err instanceof RateLimitError && attempt < 3) {
      const delay = Math.pow(2, attempt) * 1000
      await new Promise(r => setTimeout(r, delay))
      return extractWithBackoff(url, schema, attempt + 1)
    }
    throw err
  }
}

Auth errors in production

401 AuthenticationError in production usually means a key was rotated or the environment variable wasn’t set in the deployment. These are not retried automatically; they require intervention.

import { AuthenticationError } from '@tabstack/sdk'

if (err instanceof AuthenticationError) {
  // Alert — this is a configuration problem, not a transient failure
  alertOps('Tabstack API key invalid or missing')
}

---

Timeouts

Default timeout is 60 seconds per request. effort: 'max' on complex SPAs can approach this. Tune per endpoint:

// Longer timeout for heavy pages
const result = await client.extract.json(
  { url, json_schema, effort: 'max' },
  { timeout: 90_000 } // 90 seconds
)

For /automate and /research (streaming), the timeout governs the initial connection, not the stream duration. Long-running tasks may continue streaming well past 60 seconds.

---

Logging

Enable debug logging during development to see full request/response detail:

const client = new Tabstack({
  apiKey: process.env.TABSTACK_API_KEY,
  logLevel: 'debug' // 'debug' | 'info' | 'warn' | 'error' | 'off'
})

In production, warn (default) is appropriate: it surfaces retry events and errors without noise.

For Python, set TABSTACK_LOG=info in the environment.

---

Bulk extraction patterns

For high-volume extraction jobs (many URLs), control concurrency to avoid rate limit errors:

import PLimit from 'p-limit'

const limit = PLimit(5) // 5 concurrent requests

const results = await Promise.all(
  urls.map(url =>
    limit(() => client.extract.json({ url, json_schema }))
  )
)