Limity počtu požiadaviek

locco uplatňuje limity počtu požiadaviek na API kľúč naprieč tromi posuvnými oknami (sliding windows). Každá požiadavka sa započítava do všetkých troch; požiadavka, ktorá prekročí ktorékoľvek z nich, je zamietnutá s chybou HTTP 429.

Predvolené hodnoty pre úroveň Enterprise

Toto sú predvolené limity pre oprávnenie ApiAccess na úrovni Enterprise. Existujú výnimky pre jednotlivé kľúče: partneri s upraveným plánom môžu mať od podpory locco nakonfigurované vlastné limity. Hlavičky X-RateLimit-Limit-* v každej odpovedi vždy odrážajú skutočný limit pre volajúci kľúč, takže klienti, ktorí tieto hlavičky čítajú, nemusia tieto hodnoty pevne kódovať (hard-code).

Tri posuvné okná

Každá požiadavka zvyšuje tri počítadlá (za sekundu, za hodinu, za deň) a je zamietnutá, ak by ktorékoľvek z nich prekročilo svoj limit. Okná sa posúvajú: napríklad hodinové počítadlo pokrýva 3600 sekúnd predchádzajúcich aktuálnej požiadavke, nie pevnú hranicu hodinového resetu.

Praktické dôsledky:

• Náraz 100 požiadaviek v jednej sekunde spotrebuje sekundovú rezervu, ale iba 100 z hodinovej kvóty 10 000.
• Stabilných 80 požiadaviek za sekundu zaplní sekundové a hodinové okná dávno predtým, ako začne byť dôležitý denný limit.
• Nočný batch job, ktorý spúšťa 1000 požiadaviek za hodinu, nikdy nedosiahne sekundový limit, ale plne sa započítava do denného limitu 200 000.

Hlavičky odpovede

Každá úspešná odpoveď obsahuje šesť hlavičiek, jednu Limit a jednu Remaining pre každé okno:

X-RateLimit-Limit-Second: 100
X-RateLimit-Remaining-Second: 97
X-RateLimit-Limit-Hour: 10000
X-RateLimit-Remaining-Hour: 9821
X-RateLimit-Limit-Day: 200000
X-RateLimit-Remaining-Day: 191402

Použite ich na reguláciu tempa požiadaviek. Klient, ktorý sleduje X-RateLimit-Remaining-Second a spomalí, keď klesne pod určitú hranicu, pri bežnej záťaži nikdy nenarazí na chybu HTTP 429.

Spracovanie chyby 429

Keď je ktorékoľvek okno zaplnené, server vráti HTTP 429 s telom:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded."
}

Odpoveď obsahuje aj hlavičku Retry-After, ktorej hodnota je počet celých sekúnd, kým sa dotknuté okno neuvoľní. Pred ďalším pokusom počkajte aspoň takto dlho. Ignorovanie Retry-After a okamžité opakovanie pokusu nepomôže: počítadlo sa neposunulo.

Odporúčaný back-off

Pre interaktívne požiadavky (jednotlivá požiadavka v toku orientovanom na používateľa):

1. Prečítajte si hodnotu Retry-After z odpovede 429.
2. Počkajte (sleep) počet sekúnd uvedený v Retry-After a potom to skúste znova.
3. Ak aj opakovaný pokus vráti 429, vynásobte oneskorenie 2 a skúste to znova.
4. Obmedzte celkový počet opakovaní na 3.

Pomocná funkcia v Pythone, ktorá implementuje túto slučku:

import time
import requests

def get_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries + 1):
        r = requests.get(url, headers=headers)
        if r.status_code != 429:
            r.raise_for_status()
            return r

        wait = int(r.headers.get("Retry-After", "1"))
        # Exponenciálny back-off navrch k Retry-After.
        wait *= 2 ** attempt
        time.sleep(wait)

    raise RuntimeError(f"Rate limited after {max_retries} retries")

Pre batch úlohy (nočná synchronizácia, hromadný import):

• Udržujte tempo na približne 80 požiadavkách za sekundu (zhruba 80 % sekundového limitu), aby ste ponechali rezervu pre súbežnú interaktívnu prevádzku.
• Počas behu sledujte X-RateLimit-Remaining-Hour. Ak sa blíži k nule, pozastavte vykonávanie, kým sa okno neposunie vpred.
• Uprednostnite stránkovanie (pagination) s veľkou hodnotou pageSize (tam, kde to endpoint podporuje) pred množstvom malých požiadaviek.