Rate limiting

Limity podľa plánu (Free / Plus / Pro / Enterprise) a hlavičky X-RateLimit-*.

Limity podľa plánu sú per-API-kľúč a per-minúta. Implementácia je sliding window v Redise - počíta posledných 60 sekúnd, nie kalendárnu minútu, takže nezáleží kedy presne začneš.

Pred overením kľúča sa kontroluje aj rozpočet neznámych kľúčov pre spoločnú IP adresu. Jeho vyčerpanie môže vrátiť 429 aj platnej integrácii za rovnakou adresou, najmä pri jej prvom volaní. Nedávno overené kľúče môžu túto kontrolu dočasne preskočiť; platnosť kľúča, prístup jeho tvorcu a limit plánu sa vždy overia znova. Táto 429 vzniká pred autentifikáciou a neobjaví sa v Analytics firmy. Nesie Retry-After, X-RateLimit-Limit a X-RateLimit-Remaining, ale nenesie X-RateLimit-Reset.

Limity podľa plánu

PlánLimit
Free30 req/min
Plus1 000 req/min
Pro2 000 req/min
Enterprise5 000 req/min

Limit reaguje okamžite na zmenu plánu - po upgrade na Pro nemusíš nič rotovať. Per-tier hodnota sa cachuje 5 minút (300 s), takže po upgrade plánu môže nový limit dotiahnuť až do tejto doby.

Rate-limit hlavičky

Každá odpoveď po autentifikácii kľúča, aj chybová (404, 409, 422 a podobne), obsahuje 3 hlavičky. Odpoveď 401 pre chýbajúci, neplatný, revokovaný, deaktivovaný alebo expirovaný kľúč ich nenesie. Pri nedostupnom všeobecnom limitovači kľúča odpoveď 503 tieto hlavičky tiež nenesie. Výnimkou je 429 z osobitného limitu operácie: zachováva hlavičky tohto limitu, takže X-RateLimit-Reset môže chýbať. Vtedy sa riaď Retry-After. Hlavičky všeobecného limitu kľúča vyzerajú takto:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1717689600
  • • X-RateLimit-Limit - maximum povolených requestov za 60 sekúnd
  • • X-RateLimit-Remaining - koľko ti ich ešte zostáva
  • • X-RateLimit-Reset - Unix timestamp (sekundy) kedy sa najstarší request v okne uvoľní

Prekročenie limitu

Po prekročení dostaneš HTTP 429 Too Many Requests:

Responsehttp
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 14
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717689614

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "details": { "limit": 1000, "retry_after_seconds": 14 }
  }
}

Hlavička Retry-After ti povie koľko sekúnd treba počkať. Klient by mal mať exponential backoff + rešpektovať Retry-After.

Quota (mesačná kvóta)

Niektoré operácie navyše čerpajú mesačnú kvótu plánu (napr. počet odoslaných e-mailov, počet AI extrakcií). Po prekročení dostaneš 402 Payment Required s kódom QUOTA_REACHED:

Response 402json
{
  "error": {
    "code": "QUOTA_REACHED",
    "message": "Tier quota reached for ai_queries",
    "details": {
      "feature": "ai_queries",
      "limit": 10,
      "current": 10
    }
  }
}

QUOTA_REACHED je oddelená od 429 (rate limit) - upgrade plánu zruší kvótu okamžite. Pozri plány.

Best practices

  • • Caching - read-only dáta (kategórie, série) cachuj na klientovi minimálne 5 min.
  • • Stránkuj rozumne -limit=100 je lepšie než 100× limit=1.
  • • Backoff - pri 429 čakaj Retry-After sekúnd, nie hneď retry.
  • • Jeden kľúč na integráciu - uľahčí to debug + revokovanie keď niečo praskne.