Limity żądań

Limit żądań określa, ile żądań możesz wysłać w krótkim czasie. Po jego przekroczeniu API odpowiada 429 („zbyt wiele żądań”), nie wykonuje operacji i informuje, jak długo należy czekać. To zabezpieczenie przed skryptami wymykającymi się spod kontroli, a nie limit ilości generowanych treści.

Zestawienie limitów

Dwa osobne limity na konto: odczyty i zapisy

Limit żądań API — wszystkich endpointów w /api/v1/* oraz zgodnych endpointów /v1/* i /v1beta/* — jest liczony na konto, a nie na klucz: limit na klucz dałoby się obejść przez tworzenie kolejnych kluczy.

Odczyty i zapisy są liczone w dwóch osobnych pulach o tej samej wielkości. Domyślny próg zabezpieczenia wynosi 1 000 żądań na 10 sekund w każdej z nich: około 100 RPS (żądań na sekundę) przy stałym ruchu, z możliwością krótkiego skoku do 1 000. To ogólne zabezpieczenie przed nadużyciami i klientem wysyłającym niekontrolowany ruch, a nie niski limit zwykłego płatnego generowania.

Mechanizm wykorzystuje token bucket, a nie licznik ze stałym oknem: pojemność wynosi 1 000, a uzupełnianie trwa 10 sekund (około 100 tokenów na sekundę). Każde żądanie zużywa jeden token; tokeny wracają równomiernie. W przeciwieństwie do stałego okna token bucket wygładza uzupełnianie na granicach okien czasowych.

Oprócz powyższej puli zapisów upload-url ma własne ogólne zabezpieczenie 1 000 żądań na 10 sekund. Osobno chroni ono autoryzację zapisu w magazynie obiektowym; zwykłe przesyłanie plików nie powinno zbliżać się do tego progu.

usage ma dodatkowe zabezpieczenie w przeciwną stronę: znacznie niższy limit 30 żądań na minutę, oprócz opisanej powyżej puli odczytów. Endpoint agreguje historyczne zadania, więc pojedyncze wywołanie jest znacznie kosztowniejsze obliczeniowo od zwykłego odczytu i samo ogólne zabezpieczenie nie wystarcza. Używaj go do uzgadniania rozliczeń, nie jako endpointu odpytywanego w pętli. Ta pula nigdy też nie przepuszcza żądań przy awarii mechanizmu limitów: gdy nie można rozstrzygnąć limitu, zawsze zwraca 429, podczas gdy inne pule mogą być skonfigurowane tak, aby przepuszczać ruch.

Niewykorzystane adresy do przesyłania plików

Niezależnie od powyższego jedno konto może mieć najwyżej 128 jeszcze niewykorzystanych adresów do przesyłania plików lub łącznie 1 GiB zadeklarowanego rozmiaru plików powiązanych z tymi adresami. Zamówienie kolejnego zwraca 429 z Too many pending uploads; finish existing uploads before requesting more i bez Retry-After.

Czekanie tu nie pomaga, więc nie pozwól ogólnej pętli ponowień nieustannie powtarzać tego żądania. Prześlij i zatwierdź pliki, dla których adresy już zamówiono (lub poczekaj, aż te adresy wygasną, co trwa około 20 minut), a miejsce zostanie natychmiast zwolnione. Zwykle taka sytuacja oznacza, że skrypt zamawia adresy hurtowo, lecz ich nie wykorzystuje. Zobacz Media.

Wszystkie pule limitów

Limity są przypisywane do poszczególnych obszarów API, dlatego wszystko w jednym obszarze przechodzi przez ten sam łańcuch middleware. Jako użytkownik API możesz napotkać pierwszych pięć:

Podane wartości są domyślne i możemy je zmienić bez wydania nowej wersji. Aktualny limit jest zawsze wskazany w nagłówku X-RateLimit-Limit i w sekcji Overview w konsoli. Ufaj nagłówkowi i nie wpisuj wartości domyślnych na stałe do kodu klienta.

Nagłówki odpowiedzi

Zwykła odpowiedź dla konta z domyślnym limitem zawiera:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

Jak wygląda przekroczenie limitu

{
  "code": 429,
  "msg": "Too many requests. Retry in a moment",
  "request_id": "req_…"
}

Status HTTP 429, z Retry-After.

Obsługa limitów

Odczytuj Retry-After. Nie ponawiaj bez przerwy w stałym odstępie. Przykłady kończą się po pięciu próbach, co zapobiega też nieskończonej pętli przy opisanym wyżej 429 dotyczącym oczekujących plików.

async function callRespectingLimits(url, init) {
  for (let i = 0; i < 5; i++) {
    const res = await fetch(url, init);

    if (res.status !== 429) return res;

    // The server already told you how long to wait; don't guess
    const wait = Number(res.headers.get('retry-after') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('persistently rate-limited');
}

import time, requests


def call_respecting_limits(method: str, url: str, **kwargs) -> requests.Response:
    for _ in range(5):
        res = requests.request(method, url, **kwargs)

        if res.status_code != 429:
            return res

        # The server already told you how long to wait; don't guess
        time.sleep(float(res.headers.get("retry-after", 1)))

    raise RuntimeError("persistently rate-limited")

Współbieżność to osobna kwestia

Liczbę trwających zadań faktycznie ograniczają poniższe czynniki, z których żaden nie jest limitem żądań:

• Dostępne saldo — każde trwające zadanie blokuje środki. Gdy saldo się wyczerpie, nowe zadania otrzymują 40201.
• Limity wydatków — dzienny, miesięczny i łączny limit klucza, dzienny i miesięczny limit zespołu (dla kluczy należących do zespołu) oraz dzienny limit platformy. Osiągnięcie dowolnego z nich powoduje 40202. Zobacz Limity wydatków.
• Możliwość wykonania — gdy model w ogóle nie może wykonać zadania, otrzymujesz 50301.

Dlatego odpowiedzią na „chcę więcej zadań działających naraz” jest zwykle doładowanie konta lub podniesienie limitu wydatków, a nie zwiększenie limitu żądań.

Prośba o zwiększenie limitu

Aktualny limit jest widoczny w sekcji Overview w konsoli. Aby poprosić o większy, rozpocznij rozmowę w sekcji Support (temat: API integration) i opisz swój ruch: szczytową liczbę żądań na sekundę, czy uruchamiasz partie zadań i jak duże są te partie. Znacznie przyspieszy to rozpatrzenie prośby.

Do tego czasu ogranicz współbieżność klienta i przestrzegaj Retry-After. Wybieraj liczbę równoczesnych zadań na podstawie obciążenia, czasu generowania i dostępnego salda, zamiast sztucznie obniżać ją do wartości dopasowanej do domyślnego limitu żądań.

Gdy sam mechanizm limitów jest niedostępny

Mechanizm limitów zależy od zewnętrznego licznika. Gdy licznik zawiedzie, ustawiona strategia określa dalsze działanie: przepuszczanie (dalsza obsługa) lub odrzucanie (ochrona limitu). Domyślnie żądania są odrzucane — „nie mogliśmy odczytać konfiguracji” nigdy nie może oznaczać „nie ma limitu”.

Przy strategii odrzucania otrzymujesz 429 z Retry-After: 1, a nie 500. To celowe: 500 oznacza „mamy awarię”, a większość klienckich SDK natychmiast ponawia takie żądania, zwiększając obciążenie podczas incydentu. 429 z Retry-After oznacza „odczekaj i wróć”, czyli właśnie właściwe działanie.

Nie traktuj więc 429 jako dowodu, że wysyłano żądania zbyt szybko. Przestrzeganie Retry-After jest poprawną reakcją w obu przypadkach.