Copy page

Rate limiting

Every Happklaar API endpoint is rate-limited. Rate limit state is tracked per token for authenticated requests and per IP address for anonymous requests.

Response headers

Every response from a /v1/* endpoint includes three rate limit headers:

Header	Type	Description
X-RateLimit-Limit	integer	Total requests allowed in the current window
X-RateLimit-Remaining	integer	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp	Seconds since epoch when the window resets

These headers are present on every API response, regardless of whether the limit has been reached.

Example response headers:

Code
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1748392800

Rate limit tiers

Tier	Limit
Authenticated (PAT)	1000 requests per hour
Anonymous	60 requests per hour

The authenticated limit applies when a valid Authorization: Bearer <PAT> header is present. The anonymous limit applies to requests without a bearer token.

For production integrations, use a PAT. The 60 req/hour anonymous limit is not suitable for regular API usage.

429 response

When the limit is exceeded, the API returns 429 Too Many Requests with a RFC 9457 error envelope:

Code
{
  "type": "https://api.happklaar.nl/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 47 seconds.",
  "instance": "/v1/recipes",
  "retry_after_seconds": 47,
  "limit": 1000
}

The retry_after_seconds extension tells you exactly how long to wait before retrying. The limit extension confirms which limit was hit.

Backoff guidance

When you receive a 429 response:

1. Read the retry_after_seconds value from the response body (or equivalently, compute X-RateLimit-Reset - <current Unix time>).
2. Wait at least that many seconds before retrying.
3. Apply exponential backoff with jitter if you are retrying in a loop — do not hammer the API immediately after the window resets.

Example retry logic (pseudocode):

Code
async function fetchWithBackoff(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const body = await response.json();
    const waitSeconds = body.retry_after_seconds ?? 60;
    const jitter = Math.random() * 5;
    await sleep((waitSeconds + jitter) * 1000);
  }
  throw new Error('Rate limit exceeded after retries');
}

Do not use the Retry-After HTTP header alone — the retry_after_seconds field in the response body duplicates that value for environments where response headers are not reliably accessible.