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

# Rate Limits

> Operation limits per subscription tier, overage pricing, and how to handle 429 responses.

# Rate Limits

SuperDocs uses operation-based limits, not request-rate limits. Each AI action that modifies, analyzes, or searches a document counts as one operation.

## Limits by tier

| Plan           | Included operations | At the limit                             | Max monthly bill |
| -------------- | ------------------- | ---------------------------------------- | ---------------- |
| **Free**       | 500/mo              | Pauses (429 error)                       | \$0              |
| **Plus**       | 2,000/mo            | Overage at \$0.015/op, up to 4,000 total | \$50             |
| **Pro**        | 10,000/mo           | Overage at \$0.015/op, no cap            | Varies           |
| **Enterprise** | Custom              | Custom                                   | Custom           |

## Document scale limits

Separate from operation quotas, the hosted service applies two scale limits so one pathological upload can never degrade the service for everyone:

| Limit                                                   | Standard value               | Error on crossing            |
| ------------------------------------------------------- | ---------------------------- | ---------------------------- |
| Sections per document                                   | 25,000 (roughly 6,000 pages) | `413` `DOCUMENT_TOO_COMPLEX` |
| Sections per chat session (all open documents combined) | 30,000                       | `413` `SESSION_TOO_FULL`     |

These are stability limits, not platform caps. The platform itself has no hard limit on document length or on the number of documents open in parallel; the standard values exist to keep the shared hosted service fast and stable. Both errors are structured: the `detail` carries `section_count` / `max_sections` (or `session_section_count` / `max_session_sections`), `limit_expandable: true`, and `contact_email`. Hitting a limit notifies the team automatically; email [hello@superdocs.app](mailto:hello@superdocs.app) and your limits are raised, typically within a day. Larger dedicated deployments are available on Pro and Enterprise.

## Handling 429 responses

There are two kinds of `429`, and they need different handling.

**1. Application 429 (quota or cooldown).** Returned as JSON with a `detail` field, and always carries a `Retry-After` header giving the number of seconds to wait before the request can succeed. When the cause is quota exhaustion (hitting the limit on the free plan), the response also carries the three `X-Usage-*` headers:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 1209600
X-Usage-Limit: 500
X-Usage-Used: 500
X-Usage-Remaining: 0

{"detail": "Your monthly operation quota (500) is exhausted. Upgrade to Pro for uninterrupted pay-as-you-go overage."}
```

Honor `Retry-After`: wait at least that many seconds before retrying. For a monthly quota it is the time until your billing cycle resets, so upgrading is usually the better path than waiting. Branch your client on the `429` status and the headers rather than string-matching the `detail` wording (the exact message may change).

**2. Infrastructure 429 (traffic surge).** Under heavy platform load, requests can be throttled before they reach the application. These responses are plain text (for example `Rate exceeded`), not JSON, and carry no `Retry-After` header. Treat any non-JSON `429` as transient: retry with exponential backoff plus jitter.

**Best practices:**

* Check the `usage` object in chat responses to track remaining operations before you hit the limit
* On an application `429`, honor `Retry-After` and branch on the `X-Usage-Limit` / `X-Usage-Used` / `X-Usage-Remaining` headers. On successful responses, read the `usage` block in the JSON body (and the SSE `usage` event) instead; those headers are only present on the `429`.
* On a plain-text `429` with no `Retry-After`, back off exponentially with jitter and retry
* Upgrade to a paid plan for uninterrupted access

## Check remaining operations

### From API responses

Every chat response includes usage data:

```json theme={null}
{
  "usage": {
    "monthly_used": 480,
    "monthly_limit": 500,
    "monthly_remaining": 20,
    "was_billable": true,
    "subscription_tier": "free"
  }
}
```

### In the browser

View your usage bar and tier limits at [use.superdocs.app](https://use.superdocs.app) → Settings. The `/v1/users/me/limits` and `/v1/users/me/usage` endpoints are web-app-only (they reject `sk_` / `lce_` keys with a `401`); from an API-key context, use the `usage` block in chat responses above.

## Monthly reset

Operations reset at the start of each billing cycle. Free plans reset monthly from account creation. Paid plans reset on each billing renewal date.