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

# Rate limits — ceilings, headers and what a 429 looks like

> The request limits the 2Fin API applies today: the platform-wide limit, sign-in, MCP and per-tool limits, the Integration API, chat and undo, with the headers sent and how to back off.

Limits keep the service responsive for everyone. Ordinary use of the app and of a well-behaved client stays far below them. The same numbers are published as JSON at [`/api-reference/rate-limits.json`](https://docs.ai2fin.com/api-reference/rate-limits.json), and as an [OpenAPI Overlay](https://docs.ai2fin.com/api-reference/overlay.json) that adds each operation's limits to the OpenAPI as `x-rate-limits`.

## The limits

| Limit | Applies to | Ceiling | Keyed by |
| - | - | - | - |
| Platform-wide | REST API routes and `/mcp` (except the routes listed below with their own limit) | 2,000 per 15 minutes | Your account when signed in, otherwise the client IP |
| Sign-in | `/api/enterprise-auth/*` sign-in, registration, verification and MFA steps, and `/api/auth/*` (not `/api/auth/me`) | 200 per 15 minutes | Client IP |
| MCP | `POST /mcp` | 200 per 15 minutes | Your account |
| MCP per tool | Individual MCP tools (table below) | 10–30 per minute | Your account and the tool |
| Integration API | `/api/integrations/v1/*` | 60 per minute | Your account |
| Chat | `POST /api/chat/stream` 30 per minute, `POST /api/chat/conversations` 10 per minute (per account); `POST /api/chat/upload` 20 per 15 minutes (per IP) | as listed | as listed |
| Undo and history | `/api/change-sets/*` and `/api/data-history/*` | 300 per minute | Your account |

On the platform-wide limit only responses with a status of 400 or above count toward the ceiling; successful requests are not counted. Health checks and `/.well-known/*` discovery documents are exempt.

The sign-in ceiling can be tightened or relaxed by the operator within fixed bounds, so read the `RateLimit-*` headers rather than hard-coding 200.

The Integration API and MCP per-tool limits are counted by each server process, so under load the effective ceiling can be somewhat higher than the number shown. Do not rely on that headroom.

### MCP per-tool limits

| Tool | Ceiling |
| - | - |
| `process_receipt`, `get_receipt_upload_url` | 10 per minute |
| `modify_transactions`, `analyze_transactions`, `lookup_tax_reference` | 20 per minute |
| `analyze_spending`, `create_transaction`, `create_expense`, `manage_budget`, `manage_trip` | 30 per minute |

Tools not listed have no limit of their own beyond the MCP limit.

## Headers

The platform-wide and MCP limits send these on every response they count:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | The ceiling of the window that applies to you |
| `X-RateLimit-Remaining` | Requests left in the window |
| `X-RateLimit-Reset` | When the window resets, as an ISO 8601 date-time |

The sign-in, chat, undo and history limits send the standard `RateLimit-Policy`, `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers instead (`RateLimit-Reset` is in seconds).

Every `429` carries `Retry-After`, in seconds.

## When you hit a limit

You get `429 Too Many Requests`. On the platform-wide limit the body looks like this:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 20 seconds.",
  "retryAfter": 20,
  "limit": 2000,
  "windowMs": 900000
}
```

Going over the platform-wide or MCP limit starts a short block, typically 20 seconds and never longer than 2 minutes (5 minutes on `/mcp`). When the block ends you get a fresh window.

On `/mcp` the `429` keeps its HTTP status and carries a JSON-RPC error so MCP clients can read it:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded",
    "data": { "errorType": "RATE_LIMIT_EXCEEDED", "retryAfter": 60, "limit": 200, "windowMs": 900000 }
  }
}
```

A per-tool limit answers the `tools/call` with a JSON-RPC error (`code` 429, `data.tool`, `data.retryAfter`, `data.limit`, `data.window`).

The Integration API answers `{ "success": false, "error": "Rate limit exceeded for integration API", "errorType": "RATE_LIMITED" }`.

## Backing off well

1. Wait at least `Retry-After` seconds before the next attempt.
2. If you retry a write, send the same [`Idempotency-Key`](https://docs.ai2fin.com/api-reference/idempotency) so the retry cannot create a duplicate.
3. Spread bulk work out. The Integration API takes up to 500 transactions in one `POST /transactions`, which is gentler than 500 single requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.