Rate limits

Każde żądanie FourA API przechodzi trzy kontrole, zanim dotrze do silnika: limity Twojego planu, współdzieloną pulę platformy dla całego ruchu, a następnie współdzieloną pulę platformy dla wywołanego endpointu. Każda kontrola może samodzielnie odrzucić żądanie i każda odpowiada inną treścią.

Trzy kontrole w kolejności

  1. Limity planu. Na co pozwala Twój plan: jakie endpointy i parametry obejmuje, ile żądań może działać jednocześnie na endpoint, ile na minutę, ile żądań przeglądarki dziennie oraz dostępne kredyty i transfer w okresie rozliczeniowym.
  2. Globalny limit platformy. Wszystko, co host API obsługuje w danym momencie, bez względu na wybrany endpoint. Odrzucenie w tym miejscu zwraca "service": "api".
  3. Limit platformy na endpoint. Ruch w wywołanej usłudze pojedynczej, proxy lub przeglądarkowej.

Twój własny plan jest weryfikowany jako pierwszy, a ta kolejność stanowi część kontraktu, a nie szczegół implementacyjny. Współdzielone pule są wspólnym zasobem, więc żądanie, które platforma i tak by odrzuciła, nie może ich zużywać przed odrzuceniem. Konto wysyłające znacznie więcej, niż pozwala na to jego plan, jest blokowane, zanim dotknie zasobów, z których korzystają inni.

Kontrole 2 i 3 zliczają całkowity ruch FourA, a nie Twój. Odrzucenie z którejkolwiek z nich interpretuj jako "FourA jest zajęte", a nie "wysłałeś za dużo". Kontrola 1 dotyczy wyłącznie Twojego konta i nic innego na platformie na nią nie wpływa.

Odrzucenie z którejkolwiek kontroli współdzielonej zwraca Twojemu kontu wszystko, co naliczyło przyjęcie żądania, zarówno limit minutowy, jak i dzienny slot przeglądarki, ponieważ żądanie nigdy nie dotarło do backendu. Nie wlicza się to również do pauzy ponawiania opisanej w sekcji Żądania na minutę: odrzuciła je przepustowość FourA, a nie Twój plan.

POST /api/auto/ nie zajmuje własnego slotu. Podwywołania Single, Proxy i Browser wykonywane w Twoim imieniu przechodzą wszystkie trzy kontrole jak każde inne żądanie, więc równoległa pula wywołań auto obciąża Twój plan poprzez swoje podwywołania. (Liczba żądań i wskaźnik sukcesu zliczają samo wywołanie auto jeden raz; podwywołania są prezentowane jako jego próby.)

Limity planu

Limit planu odpowiada nagłówkiem X-FourA-Limit wskazującym, który limit odrzucił wywołanie. Ten sam kod znajduje się w treści pod kluczem reason, co pozwala na warunkową obsługę bez odczytywania nagłówków. Każda treść odpowiedzi dotycząca limitu planu zawiera error, reason i documentation; pozostałe pola zależą od danego limitu.

X-FourA-Limit Status Co zostało wyczerpane
plan_limit_feature 403 Wywołany endpoint lub parametr exitCountries, exitState, exitCity, exitAsn czy exitOs nie jest objęty Twoim planem
plan_limit_premium 403 exitClass: premium nie jest objęty Twoim planem lub żądanie Proxy wskazuje exit location przy braku dostępnego transferu premium
plan_limit_concurrency 429 Jednoczesne żądania do tego endpointu
plan_limit_rate 429 Liczba żądań na minutę do tego endpointu
plan_limit_browser_daily 429 Liczba żądań przeglądarki na dany dzień
plan_limit_credits 429 Płatne kredyty w danym okresie rozliczeniowym
plan_limit_bandwidth 429 Przepustowość w danym okresie rozliczeniowym

Wartości stojące za każdym limitem wynikają z Twojego planu, a zakładka Limits & Features w sekcji Usage & Limits zestawia je z bieżącym zużyciem. Nie wpisuj ich na stałe w kodzie: każde odrzucone żądanie zwraca limit, który spowodował odmowę.

Odrzucone żądanie nic nie kosztuje. Wynikiem jest rate_limit, a rozliczane jest wyłącznie success.

Endpoint lub parametr nieobjęty planem

Błąd 403 z plan_limit_feature oznacza, że wywołanie dotyczyło elementu nieuwzględnionego w planie. Weryfikacja następuje przed naliczeniem czegokolwiek, więc odrzucone wywołanie nie wpływa na limity częstotliwości ani liczniki dzienne.

{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

Ten sam kod i status są zwracane w odpowiedzi na wywołanie POST /api/proxy/, które ustawia exitCountries, exitState, exitCity, exitAsn lub exitOs w planie bez targetowania geograficznego. Ciąg error wskazuje nazwę parametru:

{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

plan_limit_premium ma taką samą strukturę dla exitClass: premium w planie bez wyjść premium. Plan obejmujący wyjścia premium, w którym wykorzystano limit ruchu premium w danym okresie, nie jest odrzucany, chyba że żądanie Proxy wskazuje konkretną lokalizację wyjściową: żądanie jest obsługiwane ze standardowej puli, a odpowiedź zwraca exitClass: standard. Żaden z tych przypadków nie zużywa wyjścia premium. Zobacz exitClass.

Żaden błąd 403 nie ustawia Retry-After. Oczekiwanie nie zmienia wyniku.

Równoczesne żądania

Współbieżność jest liczona dla każdego endpointu: Twój plan ma osobny limit dla Single, osobny dla Proxy i osobny dla Browser. Żądanie przekraczające limit zwraca kod 429 z nagłówkiem Retry-After: 1:

{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}

in_flight zlicza również odrzucone requesty, więc wskazuje co najmniej o jeden więcej niż limit.

Rozwiązaniem jest ograniczenie własnej współbieżności zamiast agresywniejszego ponawiania prób. Odpowiedź na błąd 429 poprzez natychmiastowe ponowne wysłanie tej samej partii wywoła kolejny błąd 429 dla każdego zawartego w niej wywołania. Sprawdź Run Requests in Parallel, aby zobaczyć gotowy wzorzec.

Requesty na minutę

Single i Proxy mają limit minutowy, mierzony w oknie ruchomym (sliding minute). Wliczają się do niego tylko zaakceptowane requesty: odrzucony request jest wycofywany z puli, więc konto, które stale wysyła nieco więcej niż wynosi jego limit, otrzymuje obsługę do wysokości limitu, zamiast odrzucenia niemal wszystkiego.

{
  "error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 613,
  "retry_after_seconds": 17
}

retry_after_seconds określa czas, po którym zostanie zaakceptowany kolejny request, jeśli w tym czasie nie wyślesz nic innego: co najmniej 1 sekunda i maksymalnie 120. Header Retry-After zawiera tę samą wartość.

Ponawianie odrzuconych requestów szybciej niż ten limit podlega osobnym regułom. Gdy liczba requestów odrzuconych przez ten limit w oknie minuty przekroczy dwukrotność dostępnej puli, wywołanie zostanie odrzucone z 30-sekundową pauzą:

{
  "error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 540,
  "refused_last_minute": 1250,
  "cooldown": true,
  "retry_after_seconds": 30
}

Odmowy w trakcie pauzy nie są zliczane, więc pauza kończy się samoczynnie wraz z upływem minuty, nawet w przypadku klienta ponawiającego próby. Aby odróżnić pauzę od zwykłego limitu, odczytaj cooldown zamiast tekstu error.

Żądania przeglądarki na dzień

Browser nie ma limitu na minutę. Limit w planie to liczba żądań przeglądarki na dzień, liczona od północy UTC, a licznik uwzględnia każde przyjęte żądanie przeglądarki, a nie tylko te zakończone sukcesem. Wywołanie Browser, które zakończy się błędem po stronie FourA przy zerowej liczbie kredytów, takie jak 503 Backend service unavailable, zwraca dzienny slot. Odpowiedzi Browser i Auto, które nie zostały odrzucone przez Twoje limity, zawierają licznik oraz limit w nagłówkach X-FourA-Browser-Used-Today i X-FourA-Browser-Limit-Per-Day: zobacz Response Headers.

{
  "error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
  "reason": "plan_limit_browser_daily",
  "documentation": "https://foura.ai/prices",
  "limit_per_day": 300,
  "used_today": 301
}

Ta odmowa nie zawiera nagłówka retry_after_seconds ani Retry-After, ponieważ czas oczekiwania wynosi godziny, a nie sekundy. Potraktuj to jako zatrzymanie i zaplanuj kolejne uruchomienie na północ UTC.

Kredyty w okresie rozliczeniowym

Liczą się tylko naliczone kredyty, co oznacza wyłącznie udane żądania. Gdy naliczona suma osiągnie liczbę kredytów dostępnych w tym okresie, kolejne żądania będą odrzucane do momentu zresetowania okresu lub dokupienia kolejnych.

{
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

hard_stop to liczba rozliczonych kredytów, po osiągnięciu której żądania w tym okresie są wstrzymywane. Odczytuj ją bezpośrednio z treści odpowiedzi zamiast obliczać samodzielnie: uwzględnia ona już dodatkowe kredyty dokupione do planu.

Przepustowość w okresie rozliczeniowym

Plany z limitem przepustowości odrzucają żądania, gdy standardowy ruch w danym okresie osiągnie ten limit. Ruch premium ma własny limit i nie wlicza się do tej puli. Dokupiona przepustowość jest traktowana tak samo jak ta zawarta w planie, a wartość error wskazuje łączną dostępną wielkość, a nie tylko to, co obejmuje sam plan.

{
  "error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
  "reason": "plan_limit_bandwidth",
  "documentation": "https://foura.ai/prices",
  "used_bytes": 53687091200,
  "limit_bytes": 53687091200,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

W obu limitach okresowych retry_after_seconds jest ograniczony do 24 godzin; resets_at to dokładny moment odnowienia okresu.

Pola limitów planu

Pole Typ Występuje w Opis
error string wszystkie Komunikat czytelny dla człowieka, zawierający limit przypisany do konta
reason string wszystkie plan_limit_ oraz nazwa limitu. Ta sama wartość co w nagłówku X-FourA-Limit.
documentation string wszystkie Link do strony planów
retry_after_seconds number concurrency, rate, credits, bandwidth Czas oczekiwania. Ta sama wartość co w nagłówku Retry-After.
limit number concurrency Jednoczesne requesty dozwolone przez plan na tym endpoincie
in_flight number concurrency Requesty aktualnie przetwarzane na tym endpoincie dla Twojego konta, wliczając odrzucony
limit_per_minute number rate Requesty na minutę dozwolone przez plan na tym endpoincie
current_rate number rate Requesty zliczone w ruchomym oknie minuty, wliczając odrzucony
refused_last_minute number rate pause Requesty odrzucone przez limit na minutę w ruchomym oknie minuty. Tylko przy 30-sekundowej pauzie.
cooldown boolean rate pause true przy 30-sekundowej pauzie za zbyt szybkie ponawianie. Nieobecne przy zwykłym odrzuceniu limitu na minutę.
limit_per_day number browser daily Requesty przeglądarkowe dozwolone przez plan na dzień
used_today number browser daily Requesty przeglądarkowe zliczone dzisiaj, wliczając odrzucony
used number credits Naliczona liczba credits w bieżącym okresie
hard_stop number credits Wartość credits, przy której requesty zostają wstrzymane w tym okresie
used_bytes number bandwidth Standardowy transfer w bieżącym okresie, w bajtach. Transfer Premium nie jest wliczany.
limit_bytes number bandwidth Bajty dostępne w tym okresie
resets_at string credits, bandwidth Znacznik czasu ISO 8601 oznaczający koniec okresu

Limity planu używają retry_after_seconds. Poniższe limity platformy używają retryAfter. Mechanizm ponawiania zapytań musi odczytywać oba pola lub nagłówek Retry-After, który jest ustawiany przez limity planu oraz błąd 503 API key check temporarily unavailable (zobacz Błędy).

Limity platformy

Weryfikacje platformy monitorują dwie wartości dla każdej usługi i jedną wspólną dla wszystkich:

  • Concurrency: ile requestów FourA przetwarza w tym samym czasie.
  • RPM: ile requestów FourA obsłużyło w ciągu ostatnich 60 sekund.

Oba liczniki są współdzielone przez wszystkich użytkowników danej usługi. Pola current i limits w poniższych odpowiedziach opisują platformę, a nie Twoje konto. Jeśli potrzebujesz własnych statystyk, odczytaj in_flight z odpowiedzi limitu planu lub otwórz Usage & Limits w panelu.

429: Przekroczono RPM

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Usługa wykorzystała dozwoloną liczbę żądań w ostatniej minucie. Poczekaj retryAfter s.

503: Przekroczono limit jednoczesnych połączeń

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Usługa przetwarza obecnie maksymalną dozwoloną liczbę równoległych żądań. Blokada zniknie w ciągu kilku sekund.

Usługa wyłączona

Gdy usługa jest tymczasowo wyłączana na czas prac konserwacyjnych, API zwraca kod 503 z innym komunikatem o błędzie:

{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

To nie jest rate limit. Usługa jest tymczasowo niedostępna. Sprawdź wartość retryAfter i ponów próbę po tylu sekundach. Zazwyczaj problem ustępuje w ciągu kilku minut.

Oba warianty 503 zawierają te same klucze, więc rozgałęziaj logikę według ciągu error, a nigdy na podstawie obecności poszczególnych pól. Service disabled oznacza przerwę techniczną, a Service at capacity współbieżność.

W wariancie przerwy technicznej current.concurrency i current.rpm mają zawsze wartość 0: request został odrzucony przed dokonaniem jakichkolwiek pomiarów.

Pola limitów platformy

Pole Typ Opis
error string Czytelny dla człowieka komunikat błędu
status number Kod statusu HTTP (429 lub 503)
service string Usługa, która odrzuciła wywołanie: single, proxy, browser lub api
retryAfter number Zalecany czas oczekiwania w sekundach przed ponowieniem próby
current.concurrency number Liczba requestów przetwarzanych przez usługę dla wszystkich klientów w momencie odrzucenia
current.rpm number Liczba requestów przyjętych przez usługę od wszystkich klientów w ciągu ostatnich 60 sekund
limits.maxConcurrency number Współdzielony limit współbieżności usługi
limits.maxRpm number Współdzielony limit na minutę usługi

Obsługa każdego odrzucenia za pomocą jednej funkcji pomocniczej

Retry-After jest ustawiany przy limitach planu, na które warto poczekać, retry_after_seconds znajduje się w ich treści, a retryAfter w treści błędów platformy. Odczytuj wszystkie trzy w tej kolejności i zatrzymuj się przy limitach planu, których żadne oczekiwanie nie rozwiąże:

import time
import requests

# Plan limits that a short wait never clears.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def wait_seconds(resp, attempt):
    header = resp.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    try:
        body = resp.json()
    except ValueError:
        return 2 ** attempt
    return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt

def fetch(url, api_key, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json={"method": "GET", "url": url},
        )

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")

        if resp.status_code in (429, 503):
            time.sleep(wait_seconds(resp, attempt))
            continue

        return resp

    raise RuntimeError("Max retries exceeded")

Dzienny limit nie odnawia się przez wiele godzin, a limit okresowy przez wiele dni, więc traktuj je jako sygnał do zatrzymania, a nie oczekiwania. Odczytaj resets_at z treści odpowiedzi, jeśli chcesz zaplanować kolejne uruchomienie.

Wskazówki

  • Ogranicz liczbę żądań wykonywanych jednocześnie zamiast ponawiać odrzuconą serię. Burza ponowień zamienia jeden błąd 429 w całą serię.
  • Najpierw odczytaj X-FourA-Limit. Wskazuje w jednym ciągu znaków, czy limit dotyczy Twojego konta, czy platformy, a żadne odrzucenie po stronie platformy go nie ustawia.
  • Nie wpisuj wartości na stałe w kodzie. Każda odpowiedź o przekroczeniu limitu planu zawiera wartość progową, która spowodowała odrzucenie, a Usage & Limits wyświetla je wszystkie.
  • Wartość retryAfter dla limitów platformy jest stała w zależności od typu: 2 sekundy dla współbieżności, 5 dla RPM, 60 dla prac konserwacyjnych.
  • Sprawdzaj error, aby rozróżnić oba błędy 503. Oba formaty zawierają current oraz limits, więc samo sprawdzenie obecności tych pól zinterpretuje przerwę techniczną jako problem ze współbieżnością.
  • Błąd 403 z kodem X-FourA-Limit dotyczy Twojego planu, a nie witryny docelowej. Strona docelowa w ogóle nie odpowiedziała.

Port proxy ma własne limity

Wszystko powyżej dotyczy API JSON. Ruch przesyłany przez proxy.foura.ai podlega osobnym limitom planu, liczonym w innych jednostkach: liczba jednocześnie otwartych tuneli, liczba otwarć tuneli na minutę oraz standardowy transfer w okresie rozliczeniowym. Te odrzucenia są zwracane jako status HTTP z nagłówkiem X-Foura-Error zamiast treści JSON, ponieważ żądanie CONNECT nie zawiera treści, w której można by go umieścić. Zobacz Proxy Port, aby sprawdzić tabelę statusów, oraz How Your Plan Is Metered, aby dowiedzieć się, z której puli pobierany jest transfer portu.

Aktualizacja: 6 listopada 2026