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

# Limits

> Plan limits, how the API signals them, and how to handle them

Every workspace has usage limits based on its plan. There are two kinds:

* **Rate limits** — how many requests you can make to certain endpoints within a time
  window. They reset as the window rolls over.
* **Usage quotas** — cumulative caps on what a workspace holds (documents, storage).
  They don't reset with time; you free space or upgrade.

Paid plans raise or remove these caps, and workspaces created before limits were
introduced are unaffected.

## Free plan limits

| Resource                                                                 | Free limit | Window / unit                           |
| ------------------------------------------------------------------------ | ---------- | --------------------------------------- |
| [`POST /v1/knowledge/ask`](/api-reference/knowledge/ask)                 | 5          | per minute                              |
| [`POST /v1/knowledge/search`](/api-reference/knowledge/search)           | 20         | per minute                              |
| [`POST /v1/knowledge/refresh`](/api-reference/knowledge/refresh-context) | 2          | per hour                                |
| Documents stored                                                         | 10,000     | count                                   |
| Total storage                                                            | 500 MB     | bytes                                   |
| Per-document size                                                        | 10 MB      | bytes / document                        |
| Shared workspaces                                                        | 1          | count (plus your personal workspace)    |
| Retained knowledge snapshots                                             | 1          | count (only the latest rebuild is kept) |

## Rate limits

The per-minute and per-hour endpoints above are request-rate limited per workspace.
When you exceed one, the API returns **`429 Too Many Requests`** with an
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` body and
standard `RateLimit-*` headers:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 14
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 14
RateLimit-Policy: 5;w=60

{
  "type": "https://api.adapter.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for 'ask'. Retry in 14s.",
  "error_code": "rate_limit_exceeded",
  "endpoint": "ask",
  "limit": 5,
  "remaining": 0,
  "window_seconds": 60,
  "retry_after": 14
}
```

Wait `Retry-After` seconds, then retry — ideally with exponential backoff and jitter for
bursts of calls. `RateLimit-Remaining` tells you how many requests are left in the
current window, so you can pace ahead of the limit.

## Usage quotas

Ingestion is bounded by the **document count**, **total storage**, and **per-document
size** caps. These are checked when you [push data](/core-concepts/custom-connectors),
and — unlike rate limits — retrying won't clear them; you must remove data or upgrade.

Because an ingest request can carry many items, the response tells you per item what
happened.

**Partial acceptance** — some items fit under the cap, some don't. You get **`200`**,
and the over-cap items are listed in `rejected` (the rest are ingested normally):

```json theme={null}
{
  "status": "accepted",
  "events": 8,
  "external_ids": ["doc-1", "doc-2", "…"],
  "rejected": [
    { "external_id": "doc-9",  "resource": "documents", "reason": "quota_exceeded" },
    { "external_id": "doc-10", "resource": "storage",   "reason": "quota_exceeded" }
  ]
}
```

**Full rejection** — nothing could be admitted (you're at or over the cap). You get
**`402 Payment Required`**, and nothing is ingested:

```json theme={null}
{
  "error_code": "quota_exceeded",
  "message": "Ingest rejected: this workspace is over its plan quota. Upgrade or free space to continue.",
  "details": {
    "rejected": [
      { "external_id": "doc-1", "resource": "storage",   "reason": "quota_exceeded" },
      { "external_id": "doc-2", "resource": "documents", "reason": "quota_exceeded" }
    ]
  }
}
```

Each rejected item's `resource` identifies which cap it hit — `documents`, `storage`, or
`doc_size` — in both the partial (`200`) and full (`402`) responses. A file upload is a
single document, so a rejected upload always returns `402`.

<Note>
  A `402` is **not** retryable the way a `429` is — the request didn't fail
  transiently, your workspace is over its quota. Free space (delete documents) or
  upgrade, then retry.
</Note>

## Workspace limits

On the free plan you can own **one shared workspace** in addition to your personal
workspace (see [Workspaces](/getting-started/workspaces)). Creating another returns
**`422 Unprocessable Entity`**:

```json theme={null}
{
  "error_code": "unprocessable_entity",
  "message": "Your plan allows 1 shared workspace(s). Upgrade to create more."
}
```

## Checking your usage

Call **`GET /v1/usage/current`** to see where a workspace stands before you hit a limit.
The `entitlements` block reports your plan and a meter per resource:

```json theme={null}
{
  "entitlements": {
    "tier": "free",
    "documents": { "used": 9800, "limit": 10000, "fraction_used": 0.98, "state": "approaching" },
    "storage":   { "used": 471859200, "limit": 524288000, "fraction_used": 0.9, "state": "approaching" }
  }
}
```

`state` is `ok`, `approaching` (≥ 80%), or `exceeded`. Poll this to show usage meters in
your app and to back off before you're rejected. Uncapped (paid) workspaces omit the
per-resource limits.

## Upgrading

Paid plans raise or remove every cap above. Upgrade from your workspace settings in
[mind.adapter.com](https://mind.adapter.com).