> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Rate limits

> Gateway sets no request rate limits on paid plans by default. This page covers the Free plan daily cap, optional per-key RPM limits, batch limits, vendor 429s, and how to retry.

Paid organizations get no request or token rate limits by default: vendor capacity bounds throughput, and [budgets and spend limits](/merge-gateway/cost/cost-governance-and-savings) bound runaway usage.

## Limits Gateway enforces

| Limit                    | Applies to                                                                                                                                                                            | On breach                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Free plan daily cap      | Organizations on the Free plan: 15 requests per UTC day. `GET` requests such as model listing don't count.                                                                            | `429 free_tier_daily_limit`, with `Retry-After` set to the seconds until the UTC day resets. Add a payment method to remove it. |
| Per-key RPM (optional)   | [Customer API keys](/merge-gateway/embedded-routing-stack/customer-api-keys) created with `rate_limit_rpm` through `POST /v1/customers/{customer_id}/api-keys`. Unset means no limit. | `429` with `Retry-After`                                                                                                        |
| Open batches             | 25 open [batches](/merge-gateway/capabilities/batch-inference) per organization, plus a short-lived cap on concurrent submits                                                         | `429 too_many_open_batches`, or `429 batch_submit_busy` with `Retry-After: 5`                                                   |
| Budgets and spend limits | Organization credit, project budgets, per-key spend limits, customer budgets                                                                                                          | `402`. See [Errors](/merge-gateway/errors#payment-and-budgets-402).                                                             |
| Inline media             | Base64 content per request: 20 MB for images, documents, and video, 25 MB for audio                                                                                                   | `413 payload_too_large`. Send a URL instead.                                                                                    |

Every key with `rate_limit_rpm` counts against one organization-wide counter in fixed 60-second windows, and each key compares that count with its own limit. Keys without a limit don't add to it. The `/v1/keys` Management API and the dashboard can't set a rate limit.

The per-key `429` body has no `code`:

```json
{ "error": { "message": "Rate limit exceeded. Please retry later.", "type": "rate_limit_error" } }
```

## Vendor rate limits

Under a [routing policy](/merge-gateway/routing/deterministic-strategies), a vendor `429` fails over to the next route, so most throttles never reach you. On a direct model call it comes back with `type: rate_limit_error`, `source: provider`, and no `Retry-After`. On a `flex`, `priority`, or `ultrafast` request, [`service_tier_fallback: true`](/merge-gateway/capabilities/service-tiers) retries once at `standard` on a vendor `429` or `503` (on a stream, only before the first token).

## Handling a 429

Retry with exponential backoff, honoring `Retry-After` when present. Stop on `free_tier_daily_limit` instead, since its `Retry-After` can be up to a day.

**`Python`**

```python title="Python"
import os
import random
import time

import requests

def create_response(payload, max_attempts=5):
    for attempt in range(max_attempts):
        resp = requests.post(
            "https://api-gateway.merge.dev/v1/responses",
            headers={"Authorization": f"Bearer {os.environ['MERGE_GATEWAY_API_KEY']}"},
            json=payload,
        )
        if resp.status_code != 429:
            return resp
        if resp.json().get("error", {}).get("code") == "free_tier_daily_limit":
            return resp
        wait = min(float(resp.headers.get("Retry-After", 2 ** attempt)), 60)
        time.sleep(wait + random.uniform(0, 1))
    return resp
```

## Reference

| Header                  | Meaning                                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The key's `rate_limit_rpm`, or the Free plan daily cap. `0` when no limit applies.                 |
| `X-RateLimit-Remaining` | Requests left in the current window. `0` when no limit applies.                                    |
| `X-RateLimit-Reset`     | Unix time the window resets. `0` when no limit applies.                                            |
| `Retry-After`           | Seconds to wait. Sent on per-key, Free plan, and `batch_submit_busy` `429`s, not on vendor `429`s. |

Gateway sets no concurrency cap on model requests and no `max_tokens` ceiling beyond the model's own. For a hard spend ceiling, use a project budget or per-key spend limit, which Gateway checks before calling any vendor.

## Next steps

#### [Errors](/merge-gateway/errors)

Every error code, including the 402 and 429 shapes

#### [Routing policies](/merge-gateway/routing/deterministic-strategies)

Failover that absorbs vendor throttles

#### [Cost governance](/merge-gateway/cost/cost-governance-and-savings)

Spend limits at organization, project, key, and customer scope