Rate Limits

Smart columns that call external APIs (HTTP, AI, Integration) enforce per-column rate limits. Use presets for common patterns or configure custom limits. Three layers of protection: proactive throttling, reactive backoff on 429, and circuit breaker on high error rates.

Presets

Pass a preset name as the rate_limit parameter when creating or updating a smart column.

Preset	Req/sec	Concurrent	Retries	Strategy	Best For
`aggressive`	500	6	3	exponential	Unlimited APIs, maximum throughput
`moderate`	50	6	3	exponential	Most commercial APIs (Clearbit, Hunter)
`conservative`	10	5	5	exponential	Strict APIs (Gemini free tier, OpenAI)
`gentle`	2	1	5	linear	Very strict APIs, sequential processing

Using a preset

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "leads",
    "name": "enriched",
    "type": "json",
    "kind": "http",
    "config": { ... },
    "rate_limit": "conservative"
  }
}

Custom Configuration

For fine-grained control, pass a custom rate limit object.

Parameter	Type	Description
`requests_per_second`required	`number`	Max requests per second (0.1, 1000)
`max_concurrent`required	`integer`	Max simultaneous requests (1, 6). Platform connection limit.
`retry_strategy`required	`string`	"exponential", "linear", or "fixed"
`max_retries`required	`integer`	Retry attempts per cell (0, 10)
`retry_delay_ms`required	`integer`	Base delay between retries in ms (100, 60000)
`cool_down_on_429`required	`boolean`	Auto-reduce rate when receiving 429 responses

Custom rate limit

{
  "rate_limit": {
    "requests_per_second": 10,
    "max_concurrent": 5,
    "retry_strategy": "exponential",
    "max_retries": 3,
    "retry_delay_ms": 1000,
    "cool_down_on_429": true
  }
}

Retry Strategies

Strategy	Delay Pattern	Example (base=1000ms, 3 retries)
`exponential`	base * 2^attempt	1s, 2s, 4s
`linear`	base * attempt	1s, 2s, 3s
`fixed`	base (constant)	1s, 1s, 1s

Circuit Breaker

If more than 50% of requests fail within a 60-second window, the column automatically pauses. This prevents wasting API calls and credits on a broken endpoint.

Circuit Breaker Triggered

When a circuit breaker trips, the column run status shows the error. Fix the underlying issue (wrong API key, endpoint down, etc.), then use hypertab_retry_failed_cells to reprocess failed cells.

429 Adaptive Backoff

When cool_down_on_429 is enabled, the system automatically reduces the request rate when receiving HTTP 429 (Too Many Requests) responses. The rate gradually recovers as successful requests resume.

Always enable cool_down_on_429: true for external APIs. This prevents your API key from being permanently blocked by aggressive rate limiting.

API Rate Limits

These are hypertab platform limits (separate from smart column rate limits).

Resource	Limit
Batch insert	10,000 rows per call
Query results (MCP)	100 rows per page
Query results (REST)	Unlimited (limit=0)
CSV export	50,000 rows inline, file storage for larger
HTTP proxy timeout	60 seconds max
HTTP proxy response	100KB truncation
Function execution	30 second timeout
WebSocket connections	1 per table per client

Error Codes

Limits & Quotas