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
- 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.
- 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". - 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ść
retryAfterdla 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ącurrentorazlimits, 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-Limitdotyczy 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.
Powiązane
- Run Requests in Parallel: Praktyczny wzorzec ograniczonej współbieżności
- Usage & Limits: Wszystkie limity planu zestawione z bieżącym zużyciem
- API Endpoints: Pełna dokumentacja parametrów
- Error Handling: Wszystkie typy błędów i odpowiedzi
- Response Headers:
X-FourA-Limit,Retry-Afteri pozostałe - Troubleshooting: Typowe problemy i ich rozwiązania