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

# Rate limits

> Control-plane HTTP rate limits, preview quotas, response headers, and how clients should handle HTTP 429.

Titan applies **different** limits depending on whether you are calling normal **control-plane** JSON APIs (tasks, executions, billing, analytics) or **preview** endpoints that run short-lived work. **Exact numbers are configured per environment**—the figures below are **typical defaults** when limits are enabled. Your live Titan deployment may use higher, lower, or disabled limits.

## Control-plane APIs (requests per minute)

Task, analytics, and billing APIs are usually throttled to a **steady requests-per-minute (RPM)** budget per caller. A common default when limiting is enabled is on the order of **\~120 RPM** per service surface (task, analytics, billing).

| Surface           | Typical RPM (when enabled) | Applies to                                                                                |
| ----------------- | -------------------------: | ----------------------------------------------------------------------------------------- |
| **Task API**      |                  **\~120** | Routes such as `/api/v1/tasks`, `/api/v1/executions`, and authenticated template actions. |
| **Analytics API** |                  **\~120** | `/api/v1/analytics/*` routes.                                                             |
| **Billing API**   |                  **\~120** | `/api/v1/billing/*` routes.                                                               |

**How callers are grouped:** when the request is tied to an authenticated **user**, counting is usually **per user**; otherwise limits often fall back to **client IP**.

**When limits are off:** operators can disable HTTP rate limiting entirely for a service. In that case you will not see throttling from this layer (other protections may still apply).

### Burst and headers

Limiters often allow a **short burst** above the steady RPM so occasional spikes do not fail immediately.

On successful responses you should see:

* **`X-RateLimit-Limit`**
* **`X-RateLimit-Remaining`**

When a request is blocked you also get **`X-RateLimit-Reset`** (Unix seconds). Titan’s control-plane limiter **does not** always set **`Retry-After`**; clients should read **`X-RateLimit-Reset`** or use exponential backoff with jitter.

### JSON body on HTTP 429 (control plane)

When the shared limiter rejects a call, the response is typically **`429 Too Many Requests`** with the standard error envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}
```

## Preview endpoints (daily quotas)

Preview routes (for example **`POST /api/v1/templates/:id/preview`** and task preview endpoints) use **daily quotas**, separate from the RPM bucket used for ordinary control-plane calls. Limits are enforced per environment and may be backed by shared storage so counts stay consistent across instances.

**Example** of the *kind* of knobs operators configure (illustrative only):

| Kind of limit                            | Example value | Meaning                                                  |
| ---------------------------------------- | ------------: | -------------------------------------------------------- |
| **Total previews per day**               |       **100** | Successful preview checks per principal per day.         |
| **Per scope (for example per template)** |        **20** | Additional ceiling for a narrower scope.                 |
| **URLs in one preview**                  |         **5** | Upper bound on URLs in a preview payload where enforced. |

If your deployment changes these values, error **messages** and headers should reflect the **configured** limits—treat any numbers in docs as non-binding examples.

### Preview HTTP 429 body (non-standard)

When preview quota is exceeded, the task API may return **429** with a **different** JSON shape (no `success` field):

```json theme={null}
{
  "error": "preview_limit_exceeded",
  "message": "Preview limit exceeded. 30 runs per day total, 5 per preview scope."
}
```

The `message` text is **environment-specific**; align product UI with what your deployment returns.

## Authentication endpoints

Sign-in, session, and token endpoints may use **separate** rate limits from the task and billing APIs. Numeric defaults are not fixed in this documentation—observe **`429`** responses and headers, or ask your operator for the policy that applies to your auth host.

## What this page does not cover

Background infrastructure—queues, workers, proxies, and internal schedulers—can impose **additional** throughput or fairness limits that are **not** the same as the REST API limits above. Those belong in operator runbooks, not in end-user API documentation.

Non-production environments sometimes **disable** control-plane throttling for convenience; production is expected to enforce sensible limits.

## Related reading

* [Credits and billing](/about-platform/credits-and-billing) — wallet, ledger, and how usage maps to debits.
* [Authentication and API keys](/get-started/authentication-and-api-keys) — scopes for billing and task APIs.
* API Reference → **Task Service API** / **Billing API** — concrete paths and response shapes.