Typowe problemy

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:

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:

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.

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):

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.

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

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 opisuje ten wzorzec, a sekcja Usage & Limits w 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ę:

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:

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

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, 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 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.

{ "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 (/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:

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

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, 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.

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

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.

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 pod kątem trwających incydentów
  2. Przejrzyj metryki swoich żądań w Dashboardzie
  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

Aktualizacja: 13 listopada 2026