# Rate limits

> URL: https://foura.ai/pl/docs/api/rate-limits
> Updated: 2026-11-06
> Index: https://foura.ai/llms.txt

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ę](#requests-per-minute): 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](https://foura.ai/docs/api/endpoints#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](https://foura.ai/docs/dashboard/quota) 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.

```json
{
  "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:

```json
{
  "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](https://foura.ai/docs/api/endpoints#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`:

```json
{
  "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](https://foura.ai/docs/how-to/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.

```json
{
  "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ą:

```json
{
  "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](https://foura.ai/docs/api/response-headers).

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](https://foura.ai/docs/api/errors)).

## 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](https://foura.ai/dashboard).

### 429: Przekroczono RPM

```json
{
  "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ń

```json
{
  "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:

```json
{
  "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:

```python
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](https://foura.ai/docs/dashboard/quota) 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](https://foura.ai/docs/api/proxy-port#responses), aby sprawdzić tabelę statusów, oraz [How Your Plan Is Metered](https://foura.ai/docs/guides/plans-and-metering), aby dowiedzieć się, z której puli pobierany jest transfer portu.

## Powiązane

- [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel): Praktyczny wzorzec ograniczonej współbieżności
- [Usage & Limits](https://foura.ai/docs/dashboard/quota): Wszystkie limity planu zestawione z bieżącym zużyciem
- [API Endpoints](https://foura.ai/docs/api/endpoints): Pełna dokumentacja parametrów
- [Error Handling](https://foura.ai/docs/api/errors): Wszystkie typy błędów i odpowiedzi
- [Response Headers](https://foura.ai/docs/api/response-headers): `X-FourA-Limit`, `Retry-After` i pozostałe
- [Troubleshooting](https://foura.ai/docs/troubleshooting/common-issues): Typowe problemy i ich rozwiązania
