Omejitve zahtevkov

locco uveljavlja omejitve zahtevkov po API ključu skozi tri drseča okna. Vsak zahtevek se šteje v vsa tri okna; zahtevek, ki preseže katero koli od njih, se zavrne s HTTP 429.

Privzete vrednosti za paket Enterprise

To so privzete omejitve za pravico ApiAccess na paketu Enterprise. Obstajajo posamezne prilagoditve po ključu: partnerji na prilagojenem načrtu lahko imajo posebne omejitve, ki jih konfigurira locco podpora. Glave X-RateLimit-Limit-* v vsakem odgovoru vedno odražajo efektivno omejitev za klicajoči ključ, zato odjemalcem, ki berejo glave, teh vrednosti ni treba trdo kodirati.

Tri drseča okna

Vsak zahtevek poveča tri števce (na sekundo, na uro, na dan) in se zavrne, če kateri koli od njih preseže svojo omejitev. Okna drsijo: števec “na uro” pokriva 3600 sekund pred trenutnim zahtevkom, ne fiksne meje urne ponastavitve.

Praktične posledice:

• Naval 100 zahtevkov v eni sekundi porabi eno sekundo rezerve, vendar le 100 od urne kvote 10 000.
• Stalna stopnja 80 zahtevkov na sekundo bo zasitila okni “na sekundo” in “na uro” veliko prej, kot bo omejitev “na dan” postala pomembna.
• Nočni batch posel, ki obdela 1000 zahtevkov na uro, nikoli ne doseže omejitve “na sekundo”, a se v celoti šteje v dnevnih 200 000.

Glave odgovorov

Vsak uspešen odgovor vsebuje šest glav, eno Limit in eno Remaining na 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

Uporabite jih za prilagoditev ritma zahtevkov. Odjemalec, ki spremlja X-RateLimit-Remaining-Second in upočasni, ko pade pod določen prag, pri normalni obremenitvi nikoli ne bo naletel na 429.

Ravnanje s 429

Ko je katero koli okno zasičeno, strežnik vrne HTTP 429 s telesom:

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

Odgovor vsebuje tudi glavo Retry-After, katere vrednost je število celih sekund do takrat, ko se prizadeto okno sprosti. Pred ponovnim poskusom počakajte vsaj toliko. Ignoriranje Retry-After in takojšen ponovni poskus ne pomaga: števec se ni premaknil.

Priporočena zakasnitev

Za interaktivne zahtevke (en zahtevek v uporabniškem toku):

1. Preberite vrednost Retry-After iz odgovora 429.
2. Počakajte Retry-After sekund, nato znova poskusite.
3. Če tudi ponovni poskus vrne 429, pomnožite zakasnitev z 2 in poskusite spet.
4. Omejite skupno število poskusov na 3.

Python pomočnik, ki implementira to zanko:

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"))
        # Eksponentna zakasnitev nad Retry-After.
        wait *= 2 ** attempt
        time.sleep(wait)

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

Za batch posle (nočna sinhronizacija, masovni uvoz):

• Nastavite ritem na približno 80 zahtevkov na sekundo (okoli 80 % omejitve na sekundo), da pustite rezervo za sočasen interaktiven promet.
• Spremljajte X-RateLimit-Remaining-Hour med tekom. Če se približa ničli, zaustavite, dokler se okno ne premakne naprej.
• Raje uporabite paginacijo z velikim pageSize (kjer endpoint to podpira) namesto veliko majhnih zahtevkov.