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

# Rate limits

> Request limits per key and per user, caps on runs in progress, and how to pace your client.

ZeroGen limits how many requests your keys send and how many runs they have in
progress at once. A request over a limit fails with `429 rate_limited` and a
`Retry-After` header.

## Request limits

Every authenticated request counts against two windows:

| Window | Limit |
| - | - |
| Each API key | 60 requests per minute |
| Each user, across all of their keys in the organization | 120 requests per minute |

Reads, waits, and writes all count. So does a request that ZeroGen refuses
after it checks the key, such as one that lacks a scope or has an invalid body,
so fix a failing request before you retry it.

Library requests count against the same windows, so paging through a large
Library uses the requests your runs need.

A request doesn't count against either window when a rate limit refuses it,
when its API key is invalid, when it comes from a browser, or when it names an
unknown endpoint or a method the endpoint doesn't accept.

Each window lasts 60 seconds from the first request it counts. When a window
ends, the next request starts a new one.

Test keys count against a separate user window of their own, so test traffic
never uses up live requests. Each test key still has its own 60-request window.

### Rate limit headers

Every authenticated response carries the state of the window that's closest to
refusing:

| Header | Description |
| - | - |
| `RateLimit-Limit` | The window's limit. |
| `RateLimit-Remaining` | Requests left in the window. |
| `RateLimit-Reset` | Seconds until the window starts over. |

Pace your client by these headers rather than by the limits on this page.

### When you're over the limit

A request over a limit fails with `429` and a `rate_limited` error. Its
`Retry-After` header gives the number of seconds to wait before every full
window has room again:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 17
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 17

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 17 seconds.",
    "retryable": true
  }
}
```

Wait at least `Retry-After` seconds, then retry the same request. Retry a
`POST` with the same `Idempotency-Key`; a `429` is never stored as the
request's outcome, so the retry runs. For details, see
[Idempotency](https://docs.zerogen.com/developers/idempotency.md).

## Runs in progress

Each organization's keys can have a limited number of runs queued or running
at once:

| Keys | Runs queued or running at once |
| - | - |
| Live keys | 10 per organization |
| Test keys | 4 per organization |

These caps count only runs that API keys started; runs your team starts in
ZeroGen don't count toward them. ZeroGen also stops admitting API runs while
the platform is at capacity.

A create over a cap, or while the platform is at capacity, fails with
`429 rate_limited` and `Retry-After: 60`, and starts nothing. Retry it after
one of your runs ends.

## URL imports

ZeroGen limits how much it downloads for each organization's `https` URL
inputs. Each organization can run up to 4 URL imports at once and import up to
10 GiB in 24 hours. A request over either limit fails with
`429 rate_limited`. To send larger or more files, upload them instead. For
details, see [Uploads and URL inputs](https://docs.zerogen.com/developers/uploads.md).


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