Ograničenja zahtjeva

locco primjenjuje ograničenja zahtjeva po API ključu kroz tri klizna prozora. Svaki zahtjev se broji u sva tri prozora; zahtjev koji premaši bilo koji od njih odbija se s HTTP 429.

Zadane vrijednosti za Enterprise paket

Ovo su zadana ograničenja za pravo ApiAccess na Enterprise paketu. Postoje pojedinačna prilagođavanja po ključu: partneri na prilagođenom planu mogu imati posebna ograničenja koja konfigurira locco podrška. Zaglavlja X-RateLimit-Limit-* u svakom odgovoru uvijek odražavaju efektivno ograničenje za ključ koji poziva, pa klijenti koji čitaju zaglavlja ne moraju tvrdo kodirati ove vrijednosti.

Tri klizna prozora

Svaki zahtjev povećava tri brojača (po sekundi, po satu, po danu) i odbija se ako bilo koji od njih premaši svoje ograničenje. Prozori klize: brojač “po satu” pokriva 3600 sekundi koje prethode trenutnom zahtjevu, a ne fiksnu granicu satnog resetiranja.

Praktične posljedice:

• Naval od 100 zahtjeva u jednoj sekundi troši jednu sekundu rezerve, ali samo 100 od satne kvote od 10 000.
• Stalna stopa od 80 zahtjeva po sekundi zasitit će prozore “po sekundi” i “po satu” puno prije nego što ograničenje “po danu” postane bitno.
• Noćni batch posao koji obrađuje 1000 zahtjeva po satu nikada ne dosegne ograničenje “po sekundi”, ali se u potpunosti broji u dnevnih 200 000.

Zaglavlja odgovora

Svaki uspješan odgovor sadrži šest zaglavlja, jedno Limit i jedno Remaining po prozoru:

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

Koristite ih za prilagodbu ritma zahtjeva. Klijent koji prati X-RateLimit-Remaining-Second i usporava kada padne ispod određenog praga nikada neće naići na 429 pod normalnim opterećenjem.

Rukovanje s 429

Kada je bilo koji prozor zasićen, server vraća HTTP 429 s tijelom:

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

Odgovor također sadrži zaglavlje Retry-After čija je vrijednost broj cijelih sekundi do kada se zahvaćeni prozor oslobađa. Pričekajte barem toliko prije ponovnog pokušaja. Ignoriranje Retry-After i odmah ponovni pokušaj ne pomaže: brojač se nije pomaknuo.

Preporučena odgoda

Za interaktivne zahtjeve (jedan zahtjev u korisničkom toku):

1. Pročitajte vrijednost Retry-After iz odgovora 429.
2. Pričekajte Retry-After sekundi, zatim ponovno pokušajte.
3. Ako i ponovni pokušaj vrati 429, pomnožite kašnjenje s 2 i pokušajte opet.
4. Ograničite ukupan broj pokušaja na 3.

Python pomoćnik koji implementira ovu petlju:

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"))
        # Eksponencijalna odgoda iznad Retry-After.
        wait *= 2 ** attempt
        time.sleep(wait)

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

Za batch poslove (noćna sinkronizacija, masovni uvoz):

• Postavite ritam na otprilike 80 zahtjeva po sekundi (oko 80% ograničenja po sekundi) kako biste ostavili rezervu za istovremeni interaktivni promet.
• Pratite X-RateLimit-Remaining-Hour tijekom rada. Ako se približi nuli, pauzirajte dok se prozor ne pomakne naprijed.
• Preferirajte paginaciju s velikim pageSize (gdje endpoint to podržava) umjesto mnogo malih zahtjeva.