Rate limits

Hit a 429? Back off and retry with jitter — failed requests cost 0 credits, so retrying is cheap. There are three throttles you can hit; this page walks through each.

What’s throttled

Every credit-spending request runs through two per-plan throttles, with one extra SmartBrowse-specific monthly quota:

Throttle	Applies to	Driven by
Requests per minute	All credit-spending endpoints	Your plan’s per-minute cap
In-flight requests	All credit-spending endpoints	Your plan’s concurrency cap
SmartBrowse runs per 30 days	`POST /v1/smartbrowse/recipes/:id/run` only	Your plan’s monthly run quota

Read-only endpoints (polling SmartBrowse runs, GET /v1/smartbrowse/usage) aren’t rate-limited.

Telling them apart

Every 429 uses error.code: rate_limited and includes error.details.reason so you can branch on it:

`reason`	What it means	Other fields in `details`
`rate_limit_per_min`	Too many requests per minute	`limit_per_min`
`max_concurrent_requests`	Too many requests in flight	`max_concurrent`
`sb_runs_per_month`	SmartBrowse monthly run quota exhausted	`used`, `limit`, `window: "30d"`

Example:

{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "request rate exceeds plan limit — upgrade plan or slow down",
    "details": { "limit_per_min": 60, "reason": "rate_limit_per_min" }
  },
  "request_id": "req_aB3xY9Kp"
}

Checking SmartBrowse quota up front

GET /v1/smartbrowse/usage returns your rolling 30-day run count, your plan caps, and your schedule allowance. It’s free to poll (credits_used: 0). Use it to show “X runs left this month” in your own UI instead of finding out the hard way.

When to retry

Retry on 429 and 5xx with a capped exponential backoff and jitter — three tries at 1s / 2s / 4s base delay with ±30% jitter is a sensible default. Don’t retry on 400, 401, 402, 403, 404, or 422. Nothing will change until you fix the request.

Get started

Features

Concepts

What’s throttled

Telling them apart

Checking SmartBrowse quota up front

When to retry

​What’s throttled

​Telling them apart

​Checking SmartBrowse quota up front

​When to retry

What’s throttled

Telling them apart

Checking SmartBrowse quota up front

When to retry