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

# Rate limits

> The request limits per API key and per IP address, and the headers that report them.

## Limits

| Limit | Value | Counted per |
| - | - | - |
| Requests per key | 120 per minute | API key |
| Requests per IP address | 300 per minute | IP address, across all keys |

Each limit uses a fixed window of 60 seconds. A window starts with the first request and ends 60 seconds later. The next request after that starts a new window.

The limit per IP address is checked first. It counts every `GET` and `HEAD` request to an endpoint from that address, including requests without a valid key. If you use several keys from the same address, for example from one server or behind a shared outgoing address, they share this budget. IPv4 addresses are counted one by one. IPv6 addresses are counted per `/64` network.

The limit per key is checked after the limit per IP address, the length of the query string and the form of the key. A request that gets this far counts against the limit per key, also when it then fails with `400`, `401`, `404` or `500`. See the order of checks in [Errors](/api/errors).

Other limits that apply to requests:

* The query string is at most 1024 characters, including the leading `?`. A longer one returns `400`.
* The `Authorization` header is not evaluated if it is longer than 256 characters. The request returns `401`.
* A `cursor` is at most 512 characters. A longer one returns `400`.

## Response headers

Once the limit per key has been checked, every response carries these headers. They refer to the limit per key.

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | The number of requests allowed per window (120). |
| `RateLimit-Remaining` | The number of requests left in the current window. |
| `RateLimit-Reset` | The number of seconds until the window ends. |

The headers are missing on responses that are sent before the key is read:

* `429` from the limit per IP address.
* `400` for a query string that is too long.
* `401` for a missing key or a key of the wrong form.
* `404` for a path that does not exist.
* `405` and the answer to `OPTIONS`.

## When you are limited

A request over a limit returns `429` with this body:

```json theme={null}
{ "error": { "code": "rate_limited", "message": "Too many requests." } }
```

These are the headers of a `429` from the limit per key. The value `23` is an example:

```text theme={null}
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23
```

`Retry-After` is the number of seconds until the window ends. Wait that long before the next request. It is present for both limits. When the limit per key is reached, the response also carries the three `RateLimit-*` headers. When the limit per IP address is reached, it does not.

## Practical guidance

* Read `RateLimit-Remaining`. When it is `0`, the next request in the same window returns `429`. Wait the number of seconds in `RateLimit-Reset`.
* After a `429`, wait the number of seconds in `Retry-After`, then retry.
* Use the largest page size that fits your use. `limit` goes up to 100 for offers and 200 for events, so you need fewer requests. See [Pagination](/api/pagination).

Example that prints the headers of a response:

```bash theme={null}
curl -i "https://app.hocdoc.com/api/v1/workspace" \
  -H "Authorization: Bearer $HOCDOC_API_KEY"
```


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