Rate limits

The Evinor API enforces a per-key request budget over a fixed one-minute window. The limit is applied per API key, so keys on the same account have independent budgets, and the limit is enforced consistently no matter which server handles your request.

By default the budget is 60 requests per minute per key. Always treat the RateLimit-Limit header as the source of truth rather than hard-coding a number.

Rate-limit headers

Every response — success or 429 — carries these headers:

Header	Meaning
RateLimit-Limit	The maximum number of requests allowed in the current window.
RateLimit-Remaining	Requests remaining in the current window.
RateLimit-Reset	Unix time, in seconds, when the window resets.

When you exceed the limit

A request over the budget is rejected with 429 and the rate-limited problem type:

{
  "type": "https://docs.evinor.ai/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "API rate limit exceeded. Retry after the window resets.",
  "request_id": "…"
}

A 429 additionally includes a Retry-After header giving the number of seconds to wait before retrying. The RateLimit-* headers are present on the 429 too, so RateLimit-Reset also tells you when the window clears.

Staying within budget

• Respect Retry-After. On a 429, wait the advertised number of seconds before retrying — don't retry immediately.
• Watch RateLimit-Remaining. Slow down as it approaches zero rather than waiting for a 429.
• Back off with jitter. If you run several workers, add randomized backoff so they don't retry in lockstep and immediately re-exhaust the window.
• Prefer webhooks over polling. To react to incidents, receive signed webhooks instead of polling the API on a tight loop.