Limity zapytań

locco nakłada limity zapytań na klucz API w ramach trzech ruchomych okien czasowych. Każde zapytanie wlicza się do wszystkich trzech limitów. Zapytanie, które przekroczy dowolny z nich, zostanie odrzucone z kodem HTTP 429.

Domyślne limity dla poziomu Enterprise

Są to domyślne limity dla uprawnienia ApiAccess na poziomie Enterprise. Istnieje możliwość nadpisania limitów dla konkretnego klucza: partnerzy korzystający ze spersonalizowanego planu mogą mieć skonfigurowane niestandardowe limity przez wsparcie locco. Nagłówki X-RateLimit-Limit-* w każdej odpowiedzi zawsze odzwierciedlają limit obowiązujący dla wywołującego klucza, dzięki czemu klienci odczytujący te nagłówki nie muszą kodować tych wartości na stałe.

Trzy ruchome okna czasowe

Każde zapytanie zwiększa trzy liczniki (na sekundę, na godzinę, na dobę) i jest odrzucane, jeśli którykolwiek z nich przekroczyłby swój limit. Okna czasowe są ruchome: na przykład licznik godzinowy obejmuje 3600 sekund poprzedzających bieżące zapytanie, a nie stałą granicę resetu o pełnej godzinie.

Konsekwencje praktyczne:

• Nagły skok o wielkości 100 zapytań w ciągu jednej sekundy wyczerpuje limit sekundowy, ale zużywa tylko 100 z godzinowej puli 10 000 zapytań.
• Stały ruch na poziomie 80 zapytań na sekundę nasyci okno sekundowe i godzinowe na długo przed tym, jak znaczenie zacznie mieć limit dobowy.
• Nocne zadanie wsadowe wykonujące 1000 zapytań na godzinę nigdy nie osiągnie limitu sekundowego, ale w pełni wlicza się do dobowego limitu 200 000 zapytań.

Nagłówki odpowiedzi

Każda pomyślna odpowiedź zawiera sześć nagłówków, po jednym Limit i jednym Remaining dla każdego okna czasowego:

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

Należy ich używać do kontrolowania tempa wysyłania zapytań. Klient, który monitoruje nagłówek X-RateLimit-Remaining-Second i zwalnia, gdy spadnie on poniżej określonego progu, nigdy nie otrzyma błędu 429 przy normalnym obciążeniu.

Obsługa błędu 429

W przypadku nasycenia dowolnego okna czasowego serwer zwraca kod HTTP 429 z następującą treścią:

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

Odpowiedź zawiera również nagłówek Retry-After, którego wartością jest liczba pełnych sekund pozostałych do odblokowania danego okna czasowego. Należy odczekać co najmniej tyle czasu przed ponowną próbą. Ignorowanie nagłówka Retry-After i natychmiastowe ponawianie próby nie przyniesie rezultatu: licznik się nie zmienił.

Zalecany mechanizm back-off

W przypadku zapytań interaktywnych (pojedyncze zapytanie w procesie widocznym dla użytkownika):

1. Odczytaj wartość Retry-After z odpowiedzi 429.
2. Odczekaj wskazaną liczbę sekund (Retry-After), a następnie ponów próbę.
3. Jeśli ponowna próba również zakończy się błędem 429, pomnóż opóźnienie przez 2 i spróbuj ponownie.
4. Ogranicz łączną liczbę ponownych prób do 3.

Pomocniczy kod w języku Python implementujący tę pętlę:

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"))
        # Wykładnicze opóźnienie nakładane na Retry-After.
        wait *= 2 ** attempt
        time.sleep(wait)

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

W przypadku zadań wsadowych (nocna synchronizacja, import masowy):

• Dostosuj tempo do około 80 zapytań na sekundę (około 80% limitu sekundowego), aby pozostawić zapas dla równoległego ruchu interaktywnego.
• Monitoruj nagłówek X-RateLimit-Remaining-Hour podczas działania procesu. Jeśli zbliża się do zera, wstrzymaj wykonywanie do momentu przesunięcia się okna czasowego.
• Wybieraj stronicowanie z dużą wartością pageSize (tam, gdzie dany endpoint to obsługuje) zamiast wielu małych zapytań.