# Typowe problemy

> URL: https://foura.ai/pl/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Rozwiązania najczęstszych problemów podczas korzystania z FourA API.

## Pusta lub niekompletna zawartość

**Objaw:** API zwraca status 200, ale pole `data` jest puste lub brakuje w nim oczekiwanej zawartości.

**Przyczyna:** Strona docelowa używa JavaScriptu do renderowania zawartości po początkowym załadowaniu strony.

**Rozwiązanie:** Przełącz się z pojedynczego endpointu na endpoint przeglądarki. Użyj `checkText`, aby zweryfikować, czy zawartość została załadowana:

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Uwaga: endpoint browser zwraca zawartość w polu `body` (a nie `data`).

## 403 Forbidden lub strony weryfikacji

**Objaw:** API zwraca kod HTML zawierający stronę weryfikacji lub stronę z odmową dostępu.

**Przyczyna:** Witryna docelowa wykryła zapytanie jako zautomatyzowane i je zablokowała.

**Rozwiązanie:** Użyj endpointu proxy do automatycznej rotacji IP:

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'
```

Jeśli problem będzie się powtarzał, zwiększ `maxTries`, aby dać rotacji proxy więcej prób.

Błąd 403 zwrócony przez cel docelowy trafia jako HTTP 200 z `status: 403` wewnątrz body. Błąd 403 samego wywołania z nagłówkiem `X-FourA-Limit` to inna sytuacja: zobacz [403 Not in Your Plan](#403-not-in-your-plan).

## Błędy przekroczenia limitu czasu

**Objaw:** Żądania kończą się błędem przekroczenia limitu czasu (timeout).

**Przyczyna:** Strona docelowa ładuje się dłużej niż skonfigurowany limit czasu.

**Rozwiązanie:** Zwiększ `timeout_ms` (wartość domyślna to 15 s dla single, 30 s dla browser, 45 s dla proxy):

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'
```

W przypadku żądań browser sprawdź również, czy wartość `checkText` rzeczywiście pojawia się na stronie. Literówka powoduje błąd wywołania z `checkText:<your text> not found`.

## 403 Brak w Twoim planie

**Objaw:** API zwraca kod 403 z nagłówkiem `X-FourA-Limit` oraz wartością `reason` równą `plan_limit_feature` lub `plan_limit_premium`.

```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"
}
```

**Przyczyna:** Twój plan nie obejmuje wywołanego endpointu lub przesłanego parametru. `plan_limit_feature` dotyczy wykluczonego endpointu, a `exitCountries`, `exitState`, `exitCity`, `exitAsn` lub `exitOs` braku geolokalizacji. `plan_limit_premium` dotyczy `exitClass: premium` bez węzłów wyjściowych premium oraz żądania Proxy ze wskazaną [lokalizacją wyjściową](https://foura.ai/docs/api/endpoints#exit-location) po wyczerpaniu transferu premium. Cel nie został wywołany, a środki nie zostały pobrane.

**Rozwiązanie:** Usuń parametr, wywołaj endpoint dostępny w Twoim planie lub zmień plan na wyższy. Karta **Limits & Features** na stronie [Usage & Limits](https://foura.ai/docs/dashboard/quota) zawiera listę funkcji dostępnych w Twoim planie. Nie ponawiaj tego samego żądania: nagłówek `Retry-After` nie jest ustawiany, ponieważ oczekiwanie nie zmieni wyniku.

## 429 Zbyt wiele żądań

**Objaw:** API zwraca kod 429.

**Przyczyna:** Jedna z dwóch weryfikacji odrzuciła wywołanie, a odpowiedź wskazuje która. Jeśli zawiera nagłówek `X-FourA-Limit`, osiągnięto jeden z limitów Twojego planu: liczbę jednoczesnych żądań, limit żądań na minutę dla danego endpointu, dzienną liczbę żądań Browser lub pulę kredytów bądź transferu w danym okresie rozliczeniowym. W przypadku braku tego nagłówka wyczerpany został współdzielony limit minutowy platformy dla danej usługi, co dotyczy ogólnego ruchu FourA, a nie Twojego.

**Rozwiązanie:** Sprawdź najpierw nagłówek `X-FourA-Limit`. Odczekaj, jeśli limit resetuje się za kilka sekund, i wstrzymaj żądania, jeśli czas jest dłuższy. Limity planu, które można odczekać, zwracają liczbę sekund w nagłówku `Retry-After` oraz w `retry_after_seconds`; limit współdzielony platformy zwraca tę wartość w `retryAfter`:

```python
import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)
```

Jeśli nagłówek zawierał `plan_limit_concurrency` lub `plan_limit_rate`, rozwiązaniem jest ograniczenie liczby jednocześnie otwartych wywołań oraz liczby wywołań uruchamianych na minutę, zamiast agresywnego ponawiania prób. Natychmiastowe ponowne wysłanie odrzuconej partii spowoduje ponowne odrzucenie całej partii. Odrzucone wywołania nie wliczają się do limitu na minutę, ale jeśli nadal napływają z częstotliwością ponad dwukrotnie przekraczającą ten limit, odrzucenia zamieniają się w cooldown: treść błędu 429 zawiera `cooldown: true` i wymaga wstrzymania na 30 sekund (`retry_after_seconds: 30`). Dokumentacja [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel) opisuje ten wzorzec, a sekcja **Usage & Limits** w [Dashboard](https://foura.ai/dashboard) pokazuje liczniki na żywo obok Twoich limitów.

## 503 Usługa niedostępna

**Objaw:** API zwraca status 503.

**Przyczyna:** Zdarza się to w trzech przypadkach:

1. **Przeciążenie usługi.** FourA przetwarza już maksymalną dozwoloną liczbę równoległych żądań na danym silniku, liczoną dla całego ruchu, a nie tylko Twojego. `Service at capacity` w polu `error`. Sytuacja ustępuje zwykle w ciągu kilku sekund.
2. **Usługa tymczasowo wyłączona.** Trwa okno serwisowe. `Service disabled` w polu `error`.
3. **FourA chwilowo nie może zweryfikować Twojego klucza.** `API key check temporarily unavailable` w polu `error`, z wartością `Retry-After: 5`. Twój klucz jest prawidłowy.

Wszystkie trzy przypadki zawierają pole `retryAfter` w odpowiedzi. Żaden z nich nie wynika z limitu planu: limity Twojego planu zawsze odpowiadają nagłówkiem `X-FourA-Limit` przy statusie 403 lub 429, nigdy przy 503.

**Rozwiązanie:** Odczekaj tyle sekund, ile wskazuje `retryAfter`, a następnie ponów próbę:

```python
import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")
```

Kod 503 przy braku wolnych zasobów oznacza, że FourA jest obciążone, więc rozwiązaniem jest wycofanie się i ponowienie próby. Jeśli żądanie jest odrzucane z kodem 429 i `X-FourA-Limit`, problem leży po Twojej stronie: zmniejsz liczbę równoległych żądań w swoim potoku.

## 504 Przekroczenie limitu czasu serwera nadrzędnego

**Objaw:** API zwraca kod 504 z komunikatem `{"error": "Upstream timeout"}`.

**Przyczyna:** Zadanie nie zakończyło się w zadeklarowanym budżecie czasu dla żądania. Wolno działający cel, rozwiązywanie wyzwania od zera lub bardzo duża strona mogą to spowodować. Nie jest to problem z Twoim kluczem, parametrami ani serwerem proxy.

**Rozwiązanie:** Przydziel wywołaniu więcej czasu lub ponów próbę. FourA czeka przez czas określony w `timeout_ms` powiększony o mały margines, więc zwiększenie tej wartości rzeczywiście wydłuża czas oczekiwania:

```json
{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}
```

W przypadku `/api/auto/` na chronionym celu pierwsze wywolanie na zimno moze potrwac kilkadziesiat sekund. Jego `timeout_ms` obejmuje cala drabinke i akceptuje wartosci do 180000.

Gdy sam `/api/auto/` wyczerpie ten budzet, wywolanie nadal zwraca HTTP 200. Body zawiera `error`, ktory zaczyna sie od `time budget exhausted`, a `status` to zwykle 504 (wczesniejsza nieudana proba moze pozostawic tam swoj wlasny status). Zwieksz `timeout_ms` lub ponow probe.

## 502 Upstream Niedostepny

**Objaw:** API zwraca 502 z `{"error": "Upstream unavailable"}` lub 503 z `{"error": "Backend service unavailable"}`.

**Przyczyna:** FourA nie mogl polaczyc sie z wlasnym silnikiem (`Upstream unavailable`) lub silnik nie zwrocil uzytecznej odpowiedzi (`Backend service unavailable`), zazwyczaj z powodu restartu instancji. W `/api/browser/` strona czeka do 10 sekund na wolna przegladarke, gdy wszystkie sa zajete, a strona wciaz oczekujaca po tym czasie jest zwracana jako ten blad 503.

**Rozwiazanie:** Ponow probe z krotkim backoffem. Oba przypadki klasyfikuja sie jako `service_error`, a rozliczany jest wylacznie `success`, wiec ponowienie nic Cie dodatkowo nie kosztuje. Jesli problem trwa dluzej niz minute lub dwie, sprawdz [strone statusu](https://updates.foura.ai/status).

## 401 Bledy Uwierzytelniania

**Objaw:** Kazde zadanie zwraca 401 Unauthorized.

**Lista kontrolna:**
1. Upewnij sie, ze header to `X-API-Key: YOUR_API_KEY` (a nie `Authorization: Bearer` lub `Api-Key`)
2. Sprawdz, czy w Twoim kluczu API nie ma dodatkowych spacji lub znakow nowej linii
3. Wygeneruj nowy klucz w [Dashboardzie](https://foura.ai/dashboard), jesli obecny mogl zostac skompromitowany

## 400 Nieprawidlowe Zadanie

**Objaw:** Wywolanie `POST /api/single/`, `/api/proxy/` lub `/api/browser/` zwraca 400 z `{"error": "Invalid request: <field>: <reason>; ..."}`.

**Przyczyna:** Pole w body Twojego zadania jest brakujace, ma nieprawidlowy typ lub wykracza poza zakres. Komunikat wymienia kazde niezaakceptowane pole oraz powod, maksymalnie do pieciu, z dopiskiem `and N more`, gdy jest ich wiecej. Nic nie zostalo pobrane, wynikiem jest `client_error`, a kredyty nie zostaja zuzyte.

**Rozwiazanie:** Popraw wymienione pola i wyslij zadanie ponownie. To samo body zwroci ten sam blad 400, wiec nie ponawiaj go bez zmian. [Dokumentacja endpointow](https://foura.ai/docs/api/endpoints) wymienia kazde pole wraz z jego typem i limitami. W `/api/auto/` ten sam blad wraca jako HTTP 200 z `status: 400` i powodem w `error`.

## 400 Cel Wskazuje na Prywatny lub Zastrzezony Adres IP

**Objaw:** API zwraca 400 z `Refusing to fetch <target>: target resolves to a private or reserved IP range`, zanim zadanie opusci FourA.

**Przyczyna:** Twoj `url` wskazuje na prywatny, loopback lub zastrzezony zakres IP (RFC 5735, RFC 6598 lub zastrzezone bloki IPv6). FourA odrzuca te cele, aby jego siec nie mogla byc wykorzystywana do laczenia sie z hostami wewnetrznymi.

**Rozwiazanie:** Pobierz publiczny URL. Jesli testujesz, uzyj publicznego celu, takiego jak `https://example.com` lub `https://httpbin.org/get`. Jesli docelowym obiektem jest uruchomiona przez Ciebie usluga, najpierw udostepnij ja pod publiczna nazwa hosta.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Nazwa hosta, której nie można rozstrzygnąć, nie jest odrzucana. Wywołanie zwraca HTTP 200 z `status: 0` i przyczyną (`could not resolve <host>: <reason>`), tak jak każdy cel, do którego FourA nie może dotrzeć, i nie podlega rozliczeniu.

## 400 Spacja w URL

**Objaw:** Single, Proxy lub Auto zwraca 400 z `invalid URL: it contains a space; encode it as %20 (the URL as sent: "...")`, zanim żądanie opuści FourA.

**Przyczyna:** URL zawiera spację lub znak kontrolny, zazwyczaj w linku pobranym ze strony w postaci dosłownej (`javascript: void(0)`, link do udostępniania z tekstem). Nic nie jest pobierane, wynik to `client_error` i kredyty nie są zużywane.

**Rozwiązanie:** Zakoduj URL przed wysłaniem (spacja to `%20`) i pomijaj linki, które nie są stronami, takie jak `javascript:`. Przeglądarka pobiera taki URL tak samo jak Chrome.

## 400 Celem jest samo API FourA

**Objaw:** API zwraca 400 z `Refusing to fetch <url>: that is the FourA API itself, not a page.`, zanim żądanie opuści FourA.

**Przyczyna:** Twój `url` wskazuje na `api.foura.ai` lub `eu.api.foura.ai`. Crawler zazwyczaj robi to, gdy rozwiązuje względny link ze strony względem adresu URL API zamiast własnego adresu URL strony, więc `/category/news/` zamienia się w `https://eu.api.foura.ai/category/news/`. Nic nie jest pobierane i kredyty nie są zużywane.

**Rozwiązanie:** Rozwiąż każdy link względem adresu URL strony, z której pochodzi, zanim go wyślesz, na przykład za pomocą `urljoin(page_url, href)` w Pythonie. [Endpoint Inspect](https://foura.ai/docs/api/inspect) (`/inspect`) to jedyny adres na hoście API, który można pobrać przez FourA.

## no_eligible_proxy podczas używania exitCountries

**Objaw:** Wywołanie `/api/proxy/` z parametrem `exitCountries` zwraca HTTP 200 z kopertą błędu JSON:

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

**Przyczyna:** Bieżąca pula proxy nie ma działającego węzła wyjściowego, którego kraj widoczny dla celu odpowiada Twojej białej liście. Pula standardowa nigdy nie przełącza się awaryjnie na niezażądany kraj, gdy ustawisz `exitCountries`. Bez `exitCountries` ta sama sytuacja zwraca `{"error": "Failed"}`: FourA nie miało węzła wyjściowego do wypróbowania, więc ponów próbę po kilku sekundach.

Żądanie, które wskazuje lokalizację wyjściową (`exitState`, `exitCity`, `exitAsn`, `exitOs` lub `exitLifetimeMin`, z `exitClass: premium`), wychodzi wyłącznie przez węzły premium. Gdy FourA nie ma już żadnego dostępnego węzła premium do wypróbowania dla tego żądania, wywołanie kończy się z `"error": "No premium exit answered for this request"` oraz tym samym `code: no_eligible_proxy`.

**Rozwiązanie:** Zachowaj żądany zakres i ponów próbę później. Pula jest odświeżana mniej więcej co dziesięć minut, więc kraj, który obecnie nie ma dopasowania, często zyskuje je w ciągu godziny.

```python
import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
```

Rozszerzaj listę krajów tylko wtedy, gdy wymagania Twojego przepływu pracy dotyczące lokalizacji rzeczywiście uległy zmianie. Ciche przejścia awaryjne (fallback) do innych krajów mogą uszkodzić dalszą logikę zależną od geolokalizacji.

## Profil przeglądarki został odrzucony

**Objaw:** Wywołanie zwraca `unknown profile '<id>'`, `no profile matches browser=...` lub `browser profile selection requires unblocker:true`.

**Przyczyna:** Przesłany `profile`, `browser`, `os` lub `version` nie znajduje się w katalogu albo przesłano profil z `unblocker: false`.

**Rozwiązanie:** Sprawdź [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles), aby zobaczyć aktualny katalog, wybierz profil z listy i pozostaw włączoną opcję `unblocker` podczas wybierania przeglądarki.

## Treść odpowiedzi (body) zawiera zniekształcony tekst

**Objaw:** `data` (lub `body`) w odpowiedzi zawiera błędy kodowania (mojibake) lub nieczytelne znaki, gdy cel używa kodowania innego niż UTF-8.

**Przyczyna:** Domyślnie FourA automatycznie dekoduje treść odpowiedzi do UTF-8 na podstawie nagłówka `Content-Type` celu lub tagu HTML `<meta charset>`. Jeśli cel podaje nieprawidłowy zestaw znaków, otrzymasz zniekształcony tekst.

**Rozwiązanie:** W przypadku danych binarnych (obrazy, protobuf, surowy dźwięk) ustaw `returnBuffer: true` w żądaniu. Single i Proxy zwracają wtedy `data` jako obiekt zawierający surowe bajty, `{"type": "Buffer", "data": [<byte values>]}`, bez stosowania transkodowania zestawu znaków.

```json
{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}
```

W przypadku celów tekstowych, które niepoprawnie deklarują swój zestaw znaków, zdekoduj surowe bajty samodzielnie: pobierz za pomocą `returnBuffer: true`, odczytaj wartości bajtów w `data.data`, a następnie zdekoduj je przy użyciu właściwego zestawu znaków.

## Nieoczekiwany HTML zamiast JSON

**Objaw:** Oczekiwano formatu JSON z witryny docelowej, ale otrzymano HTML.

**Przyczyna:** Strona docelowa może serwować inną zawartość w zależności od nagłówków.

**Rozwiązanie:** Dodaj nagłówek `Accept` i włącz `unblocker`, aby uzyskać realistyczne nagłówki przeglądarki:

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'
```

Możesz także ustawić `tryJsonData` na `true`, aby FourA automatycznie parsowało odpowiedzi JSON.

## Treść odpowiedzi to strona testowa, a nie zawartość

**Objaw:** Wywołanie powiodło się, `status` ma wartość 200, ale `data` (lub `body`) to weryfikacja bota zamiast oczekiwanej strony.

**Przyczyna:** Cel uruchomił test na obecność bota, na który FourA natrafiło, lecz nie zdołało go przejść. Odpowiedź o tym informuje: Single i Proxy zwracają `defense` z wartością `solved: false`, a Browser zwraca `defenseSolved: false` z nazwą dostawcy w `defenses.present`.

**Rozwiązanie:** Sprawdź najpierw `defense.vendor`, a następnie eskaluj. Wypróbuj inny profil przeglądarki w Single, przejdź na Proxy, aby zmienić węzeł wyjściowy, lub użyj Browser, aby uruchomić JavaScript. Pełny opis pól i lista dostawców: [Weryfikacje witryn](https://foura.ai/docs/api/site-checks).

Dodaj podciąg `validate.data.accept`, który występuje tylko na właściwej stronie. Strona weryfikacyjna rozpoznana przez FourA nigdy nie jest traktowana jako sukces: jest zwracana z nagłówkiem `X-FourA-Check-Page` i nie podlega opłacie. Bez `validate` nierozpoznana przez FourA strona weryfikacyjna zwrócona z kodem HTTP 200 liczy się jako sukces, a błąd wykryjesz dopiero na dalszych etapach, zamiast na poziomie wywołania.

## Problem nadal występuje?

Jeśli żadne z powyższych rozwiązań nie działa:

1. Sprawdź stronę [status page](https://updates.foura.ai/status) pod kątem trwających incydentów
2. Przejrzyj metryki swoich żądań w [Dashboardzie](https://foura.ai/dashboard)
3. Skontaktuj się ze wsparciem pod adresem support@foura.ai, podając szczegóły żądania (dołącz `X-FourA-Request-Id` z nieudanej odpowiedzi)

## Następne kroki

- [Obsługa błędów](https://foura.ai/docs/api/errors): dokumentacja kodów błędów API
- [Limity zapytań](https://foura.ai/docs/api/rate-limits): limity planów i platformy wraz z polami
- [Statusy żądań](https://foura.ai/docs/api/outcomes): jak statusy klasyfikują przebieg żądania
- [Weryfikacje witryn](https://foura.ai/docs/api/site-checks): co oznacza pole `defense`
- [Wybór odpowiedniego endpointu](https://foura.ai/docs/guides/choosing-task-type): dobierz najlepsze podejście dla swojego celu
- [Przegląd Dashboardu](https://foura.ai/docs/dashboard/overview): monitoruj swoje żądania
