# Limits, paging, idempotency

> Rate limits, idempotency keys and request size for the REST API and the MCP server, and the paging that is coming.

## Rate limits

### REST API (live)

Each API key may make **60 requests a minute** unless the key carries a
different limit of its own. The window is a calendar minute. Past the
limit you get:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 41

{ "error": "rate_limited", "retry_after": 41 }
```

Wait `Retry-After` seconds, then try again.

### MCP server and new credentials (preview)

Each credential has its own limit (60 requests a minute by default), and the
whole workspace has a shared one (600 requests a minute across all its
credentials), so creating more credentials does not buy more traffic. Every
answer carries the credential's window:

```http
RateLimit-Limit: 60
RateLimit-Remaining: 12
RateLimit-Reset: 41
```

Past either limit you get `429` with `Retry-After`, and the body says which
limit you hit:

```json
{ "error": "rate_limited", "scope": "credential", "retry_after": 41 }
```

`scope` is `credential` or `organization`.

## Idempotency

A retry must never do the same thing twice. Send an `Idempotency-Key` header,
any unique string, and reuse it only when you retry the same request.

| Endpoint | Idempotency-Key | Sending the same key again |
|---|---|---|
| `POST /api/v1/leads` | Optional; the first 128 characters are used | `409 duplicate_request`; no second lead |
| `POST /api/v1/motions/{id}/start` | **Required**, 1 to 100 visible ASCII characters | The same answer as the first time. A key reused for a different company answers `409 idempotency_key_reused` |

On motion starts, an idempotency key belongs to the API key that sent it, so
two integrations cannot collide.

**Coming soon:** `Idempotency-Key` on every write, kept for 24 hours; the same
key with a different body will answer `422 idempotency_mismatch`, and a key
whose first request is still running will answer `409`.

## Request size

| Where | Largest body |
|---|---|
| `POST /api/v1/leads` | 256 KB |
| `POST /api/v1/motions/{id}/start` | 32 KB |
| The MCP server (preview) | 1 MB |

## Paging

**Coming soon.** Lists will use keyset pages. You pass `limit` (1 to 100) and
the `cursor` from the previous page, and every list answers the same shape:

```json
{ "rows": [], "nextCursor": "…", "total": 1234 }
```

`total` is the exact count. Keep passing `nextCursor` until it is `null`.

Source: https://dev.funnelone.ai/rest/limits/