Rychlostní limity

locco uplatňuje rychlostní limity pro každý API klíč napříč třemi posuvnými okny (sliding windows). Každý požadavek se započítává do všech tří; požadavek, který překročí jakýkoli z nich, je zamítnut s chybou HTTP 429.

Výchozí hodnoty pro úroveň Enterprise

Toto jsou výchozí limity pro oprávnění ApiAccess v úrovni Enterprise. Existují výjimky pro jednotlivé klíče: partneři s upraveným plánem mohou mít od podpory locco nakonfigurovány vlastní limity. Hlavičky X-RateLimit-Limit-* v každé odpovědi vždy odrážejí efektivní limit pro volající klíč, takže klienti, kteří tyto hlavičky čtou, nemusí tyto hodnoty pevně kódovat (hard-code).

Tři posuvná okna

Každý požadavek zvyšuje tři počítadla (za sekundu, za hodinu, za den) a je zamítnut, pokud by některé z nich překročilo svůj limit. Okna jsou posuvná: například hodinové počítadlo pokrývá 3600 sekund předcházejících aktuálnímu požadavku, nikoli pevnou hranici hodinového resetu.

Praktické důsledky:

• Nárazových 100 požadavků v jedné sekundě vyčerpá sekundovou rezervu, ale pouze 100 z hodinové kvóty 10 000.
• Stabilních 80 požadavků za sekundu nasytí sekundová a hodinová okna dávno předtím, než začne hrát roli denní limit.
• Noční batch úloha spouštějící 1000 požadavků za hodinu nikdy nenarazí na sekundový limit, ale plně se započítává do denního limitu 200 000.

Hlavičky odpovědi

Každá úspěšná odpověď obsahuje šest hlaviček, jednu Limit a jednu Remaining pro 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žijte je k regulaci tempa požadavků. Klient, který sleduje X-RateLimit-Remaining-Second a zpomalí, když hodnota klesne pod určitou hranici, při běžné zátěži nikdy nenarazí na chybu 429.

Zpracování chyby 429

Když je jakékoli okno nasyceno, server vrátí HTTP 429 s tělem:

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

Odpověď také obsahuje hlavičku Retry-After, jejíž hodnota je počet celých sekund, dokud se zasažené okno neuvolní. Před dalším pokusem počkejte alespoň takto dlouho. Ignorování Retry-After a okamžité opakování nepomůže: počítadlo se neposunulo.

Doporučený back-off

Pro interaktivní požadavky (jeden požadavek v toku směřujícím k uživateli):

1. Přečtěte hodnotu Retry-After z odpovědi 429.
2. Počkejte (sleep) počet sekund uvedený v Retry-After a poté to zkuste znovu.
3. Pokud i opakovaný pokus vrátí 429, vynásobte zpoždění dvěma a zkuste to znovu.
4. Omezte celkový počet opakování na 3.

Pomocná funkce v Pythonu, která implementuje tuto smyč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ální back-off navíc k Retry-After.
        wait *= 2 ** attempt
        time.sleep(wait)

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

Pro batch úlohy (noční synchronizace, hromadný import):

• Udržujte tempo na zhruba 80 požadavcích za sekundu (přibližně 80 % sekundového limitu), abyste ponechali rezervu pro souběžný interaktivní provoz.
• Během běhu sledujte X-RateLimit-Remaining-Hour. Pokud se blíží k nule, pozastavte úlohu, dokud se okno neposune vpřed.
• Upřednostněte stránkování s velkou hodnotou pageSize (tam, kde to endpoint podporuje) před mnoha malými požadavky.