> ## Documentation Index
> Fetch the complete documentation index at: https://webscrape.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> What's throttled, how to detect it, and how to back off.

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:

```json theme={null}
{
  "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.