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

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

{
  "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 — and send the token. If 600 per minute is genuinely not enough for what you are building, write to [email protected] and tell us what you are doing; we would rather raise the limit than have you scrape the HTML.