# Yappy API rate limits

The limits are generous because the data is small, public, and cacheable. You
should not have to think about this page unless something has gone wrong in a
loop.

## The ceilings

| Caller | Limit |
|---|---|
| Anonymous (no token) | 120 requests per minute per IP |
| Registered OAuth client | 600 requests per minute per client |
| `POST /api/v1/batch` | Counts as one request, not one per operation |
| MCP `tools/call` | Counted with the REST limit, same bucket |

A batch of 20 reads costs one request. If you are polling several things at
once, batching is the cheapest path by a factor of twenty.

## Headers

Every response — success or failure — carries the RFC-style rate limit headers:

```
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 43
RateLimit-Policy: 120;w=60
```

`RateLimit-Reset` is seconds until the window rolls over, not a timestamp. Read
`RateLimit-Remaining` and self-throttle before you are refused, rather than
treating `429` as flow control.

## When you are limited

```
HTTP/2 429
Retry-After: 12
RateLimit-Remaining: 0
Content-Type: application/problem+json
```

```json
{
  "type": "https://yappy.biz/developers/errors#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "120 requests per 60s exceeded. Retry in 12 seconds, or batch your reads via POST /api/v1/batch."
}
```

Wait `Retry-After` seconds. Do not retry sooner — a retry inside the window is
refused again and still counts.

## Backing off well

Exponential backoff with full jitter, capped at about 60 seconds:

```
delay = random(0, min(60, base * 2 ** attempt))
```

Give up after five attempts and surface the failure rather than looping. An agent
stuck in a retry loop against a documentation API is a bug worth reporting.

## Not being limited at all

Most of what this API returns changes a few times a month. Two things make the
limits irrelevant:

- **Conditional requests.** Every `GET` returns a strong `ETag`. Send
  `If-None-Match` and a `304` costs you nothing but the round trip.
- **Cache headers.** Responses carry a real `Cache-Control` `max-age`; honouring
  it removes most polling entirely.

If you are watching for a new Yappy release, poll `/api/v1/releases/latest` with
an `ETag` every few hours — not every few seconds. Nothing ships that fast.

## Higher limits

Register an OAuth client — [self-serve, no sales
call](https://yappy.biz/developers/authentication) — and send the token. If 600
per minute is genuinely not enough for what you are building, write to
**support@yappy.biz** and tell us what you are doing; we would rather raise the
limit than have you scrape the HTML.

---

Canonical: https://yappy.biz/developers/rate-limits/ · Last updated: 2026-08-25