Rate limits and quotas

How per-key rate limits and per-project monthly quotas work in the Krun API, and how to handle 429 errors.

Krun applies two kinds of limits:

	Scope	Window	Error
Rate limit	Per API key	Requests per minute	429 RATE_LIMITED
Quota	Per project	Calendar month (UTC)	429 QUOTA_EXCEEDED

Limits are set per project and per API key during the closed beta, so they can differ between projects. Contact support if you need higher limits.

Rate limits

Each API key can make a limited number of requests per minute, counted in fixed one-minute windows. Every response includes the current state:

Header	Description
X-RateLimit-Limit	Requests allowed per window for this key.
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Seconds until the window resets.

When you exceed the limit, the API returns 429 with RATE_LIMITED and a Retry-After header with the number of seconds to wait:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "...",
    "request_id": "req_..."
  }
}

Wait for Retry-After before sending more requests. To stay under the limit, ask several questions about the same text in one request instead of one request per question.

Quotas

A project can have monthly limits on:

• decisions: each question in a successful request counts as one decision,
• input tokens: the sum of usage.input_tokens of successful requests.

Only successful decisions count. When a quota is exhausted, the API returns 429 with QUOTA_EXCEEDED until the next calendar month (UTC). Retrying doesn’t help.

Quotas are checked before each request, so concurrent requests can go slightly over a quota.

Handling 429 in Python

import time

import krun

try:
    result = client.decide(context="...", questions={...})
except krun.RateLimitError as e:
    time.sleep(e.retry_after or 1)
    result = client.decide(context="...", questions={...})
except krun.QuotaExceededError:
    ...  # stop sending requests and alert your team