Limity API

Dla: Programista

Przykłady na tej stronie używają adresu . Zmień adres

Limity chronią drukarnię przed integracją, która przez pomyłkę wysyła za dużo albo za ciężkich zapytań. Wszystkie wartości na tej stronie są częścią kontraktu API: ich zmianę zapowiada historia zmian API.

Limit żądań

Domyślnie integracja może wysłać 120 żądań na minutę, wszystkimi swoimi kluczami razem. Limit Twojej integracji podaje nagłówek RateLimit-Limit każdej odpowiedzi na żądanie z działającym kluczem, także odrzucone za brak zakresu albo przez limity zapytania. Licznik zeruje się na początku każdej minuty zegarowej. Liczy się każde żądanie z działającym kluczem, także zakończone błędem.

Jeśli integracja potrzebuje więcej, administrator drukarni może poprosić o inny limit, pisząc na [email protected] z nazwą integracji i uzasadnieniem.

Nagłówki

Odpowiedzi na żądania z działającym kluczem mają nagłówki stanu limitu. Odpowiedź 401 albo 403 na klucz błędny, wygasły, bez akceptacji albo wstrzymany ich nie ma.

Nagłówek	Znaczenie
`RateLimit-Limit`	Limit żądań integracji na minutę.
`RateLimit-Remaining`	Ile żądań zostało w bieżącej minucie.
`RateLimit-Reset`	Za ile sekund licznik się wyzeruje.
`Retry-After`	Tylko po przekroczeniu limitu: ile sekund odczekać.

Po przekroczeniu limitu

API odrzuca żądanie, zanim przeczyta zapytanie, więc nic z niego się nie wykonuje. Odpowiedź ma status HTTP 429 i jeden błąd z kategorią RATE_LIMITED w errors, bez data. Czas oczekiwania podają nagłówek Retry-After i params.retryAfterSeconds:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17

{
  "errors": [
    {
      "message": "API rate limit exceeded",
      "extensions": {
        "code": "RATE_LIMITED",
        "params": {
          "retryAfterSeconds": 17
        },
        "message": "API rate limit exceeded",
        "requestId": "4f0e9a8e-2f6d-4c9e-8b17-7b0d6a523c41"
      }
    }
  ]
}

Odczekaj podany czas i ponów żądanie. Nie ponawiaj od razu w pętli: odrzucone żądania też zużywają limit. Integracja, która regularnie dochodzi do limitu, powinna rozłożyć żądania w czasie, pobierać większe strony albo pytać o kilka list w jednym zapytaniu, jak sonda z przepisu Zmiany na żywo w ekranach integracji.

Limity zapytania

API sprawdza każde zapytanie przed wykonaniem. Zapytanie ponad limit jest odrzucane w całości, ze statusem HTTP 400 i błędem BAD_REQUEST z jednym z sub-kodów:

Limit	Wartość	Sub-kod
Głębokość zapytania	6 poziomów zagnieżdżenia pól (pole główne to poziom 1)	`API_QUERY_TOO_DEEP`
Rozmiar strony	Od 1 do 100	`API_PAGE_SIZE_EXCEEDED`
Szacowany koszt	Najwyżej 200	`API_QUERY_TOO_COMPLEX`
Rozmiar dokumentu	Najwyżej 5000 pól po rozwinięciu fragmentów	`API_QUERY_TOO_COMPLEX`

Rozmiarem strony jest wartość każdego argumentu i pola wejściowego o nazwie z listy pageSize, first, last, limit, take, gdziekolwiek występuje w zapytaniu: jako literał, zmienna albo pole obiektu wejściowego.

params błędu podaje szczegóły: przekroczoną wartość i limit. Opis każdego sub-kodu znajdziesz na stronie Błędy.

Jak liczony jest koszt

Koszt szacuje, ile obiektów API będzie musiało pobrać, zanim wykona zapytanie:

każde wybrane pole obiektowe (zwracające obiekt albo listę obiektów) kosztuje 1, raz dla każdego obiektu nadrzędnego; pola skalarne, np. tekst, liczba czy data, są darmowe;
pola wewnątrz listy ze stronami liczą się tyle razy, ile rekordów ma strona (bez podanego rozmiaru strony koszt przyjmuje 25);
pola wewnątrz listy bez stron liczą się tyle razy, ile elementów lista zwykle ma (domyślnie 10);
część kosztownych pól ma wyższą wagę;
każda wartość na liście filtra in albo notIn dodaje 1.

Przykład: lista ze stroną 50 rekordów (1), jej pole items (1) i jedno powiązanie w każdym rekordzie (50) kosztują razem 52. Ta sama lista ze stroną 100 rekordów i trzema powiązaniami kosztuje 302, czyli więcej niż limit 200. Gdy przekroczysz limit, zmniejsz stronę albo pobierz część powiązań osobnym zapytaniem.