Production Reliability

Reference

Caching behavior, retry handling, error patterns, timeouts, and operational decisions for running Tabstack dependably in production.

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: {
    /* ... */
  },
});

# Price monitoring, always fresh
result = client.extract.json(
    url="https://competitor.com/pricing",
    nocache=True,
    json_schema={...},
)

curl -X POST https://api.tabstack.ai/v1/extract/json \
  -H "Authorization: Bearer $TABSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://competitor.com/pricing",
    "nocache": true,
    "json_schema": { "type": "object" }
  }'

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:

TypeScript
Python

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

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

client = Tabstack(max_retries=0)

# Or per-request:
client.with_options(max_retries=5).extract.json(url=url, json_schema=json_schema)

Error handling patterns

Distinguish 422 from 500

A 422 UnprocessableEntityError means the URL was malformed or inaccessible, or the input was invalid (for example a bad schema). It does not mean the page was fetched but extraction failed. That surfaces as a 500. See the Error Reference for the full definition.

Retrying with effort: 'max' only helps a 500 where the page was fetched but extraction failed because it needed full browser rendering. It will not fix a 422: a genuine malformed URL, DNS, connection, SSL, 404, or robots failure needs a corrected or different URL, not a retry.

TypeScript
Python

import Tabstack, { InternalServerError } from "@tabstack/sdk";

try {
  return await client.extract.json({ url, json_schema });
} catch (err) {
  if (err instanceof InternalServerError) {
    // Page was fetched but extraction failed: retry with full rendering
    return await client.extract.json({
      url,
      json_schema,
      effort: "max",
      nocache: true,
    });
  }
  // A 422 (UnprocessableEntityError) means the URL is bad: fix it, do not retry.
  throw err;
}

from tabstack import InternalServerError

try:
    return client.extract.json(url=url, json_schema=json_schema)
except InternalServerError:
    # Page was fetched but extraction failed: retry with full rendering
    return client.extract.json(
        url=url,
        json_schema=json_schema,
        effort="max",
        nocache=True,
    )
# A 422 (UnprocessableEntityError) means the URL is bad: fix it, do not retry.

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:

TypeScript
Python

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;
  }
}

import time
from tabstack import RateLimitError


def extract_with_backoff(url, schema, attempt=0):
    try:
        return client.extract.json(url=url, json_schema=schema)
    except RateLimitError:
        if attempt < 3:
            delay = 2 ** attempt
            time.sleep(delay)
            return extract_with_backoff(url, schema, attempt + 1)
        raise

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.

TypeScript
Python

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");
}

from tabstack import AuthenticationError

if isinstance(err, AuthenticationError):
    # Alert: this is a configuration problem, not a transient failure
    alert_ops("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:

TypeScript
Python

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

# Longer timeout for heavy pages (seconds)
result = client.with_options(timeout=90.0).extract.json(
    url=url, json_schema=json_schema, effort="max"
)

For /automate and /research (streaming), the SDK applies a default timeout of 600,000 ms (10 minutes) when you haven’t set a client timeout, so long-running agents run to completion without you raising it. An explicit shorter client timeout is still honored, so don’t set one below your expected task duration.

Serverless and edge functions

Serverless platforms cap how long a function can run, and that cap is often shorter than a Tabstack call. If your function’s maximum duration is lower than the call, the platform stops the function before Tabstack responds.

Budget generously. Effort level sets page-fetch time, but an /extract/json call against an array schema spends most of its time on extraction and routinely runs past 30 seconds at any effort level, with a long tail beyond two minutes. /automate and /research can stream for several minutes. See Effort levels for measured numbers.

There is no async job mode and no webhook callback. Every endpoint is a single synchronous request, and /automate and /research stream over SSE, so the connection must stay open for the whole call. That means you cannot escape a platform timeout by submitting work and polling for it later; you have to give the call room to finish, or move it off the request path yourself.

Set the function’s max duration above your expected call time:

Vercel: raise maxDuration in the route segment config (or vercel.json). The default on Hobby is short, so give extract and generate headroom for max effort, and give /automate and /research room for the full task.
AWS Lambda: raise the function timeout to cover the call. Lambda’s own ceiling is 15 minutes, which is enough for anything Tabstack does. The problem is usually in front of it: API Gateway applies a 29-second integration timeout that you cannot raise, and it returns a 504 to your caller while the Lambda keeps running. Since raising it is not an option, an /extract/json array extraction behind API Gateway needs to move off the request path.

Running the call off the request path

There is no async or webhook mode to fall back on, so if a call can outlast your platform’s limit, you own the queueing. The shape that works:

Your handler validates the request, writes a record with a pending status, enqueues the job, and returns 202 immediately with an ID.
A worker with a long timeout picks up the job and makes the Tabstack call. On Lambda, that means invoking a second function with InvocationType: 'Event' so the caller doesn’t wait, or a queue with an SQS-triggered consumer. On Vercel, a background function or a queue like QStash or Inngest.
The worker writes the result back against the ID.
Your client polls the ID, or you notify it yourself over websocket, SSE, or a push.

The worker is where the generous SDK timeouts matter: leave them alone and let the call finish rather than capping it below the work.

If the call comfortably fits inside your function’s limit, skip all of this and call Tabstack directly. This is for array extractions, max effort on heavy pages, and the streaming endpoints.

For the streaming endpoints, the function also has to stay alive for the whole stream. Run /automate and /research from a route that supports streaming or long-lived responses, not a short synchronous handler. See Streaming patterns for edge-runtime examples.

Logging

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

TypeScript
Python

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

import os

# Python logging is controlled by an environment variable:
os.environ["TABSTACK_LOG"] = "debug"  # "info" | "debug"

client = Tabstack()

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:

TypeScript
Python

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 }))),
);

from concurrent.futures import ThreadPoolExecutor

# 5 concurrent requests
with ThreadPoolExecutor(max_workers=5) as executor:
    results = list(
        executor.map(
            lambda url: client.extract.json(url=url, json_schema=json_schema),
            urls,
        )
    )