Dokumentacja › Rozwiązywanie › Typowe problemy

Typowe problemy

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

Pusta lub niekompletna treść

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

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

Rozwiązanie: Przełącz się z endpointu single na endpoint browser. Użyj checkText, aby sprawdzić, czy treść 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 przeglądarki zwraca treść w polu body (a nie w data).

Błąd 403 Forbidden lub strony z mechanizmem CAPTCHA

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

Przyczyna: Strona docelowa wykryła request jako zautomatyzowany i go zablokowała.

Rozwiązanie: Użyj endpointu proxy do automatycznej rotacji adresów 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 nadal występuje, zwiększ maxTries, aby dać rotacji proxy więcej prób.

Błędy timeout

Symptom: Żądania kończą się błędem timeout.

Przyczyna: Strona docelowa ładuje się dłużej niż skonfigurowany timeout.

Rozwiązanie: Zwiększ timeout_ms (domyślnie 15s dla single, 30s dla browser, 45s 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ń z przeglądarki sprawdź również, czy wartość checkText faktycznie występuje na stronie. Literówka zawsze spowoduje timeout.

429 Too Many Requests (Limit RPM)

Objaw: API zwraca status 429 z komunikatem "rate limit exceeded".

Przyczyna: Przekroczono limit żądań na minutę (RPM). Jest to coś innego niż limity współbieżności (patrz błąd 503 poniżej).

Rozwiązanie: Użyj pola retryAfter z odpowiedzi, aby odczekać odpowiednią ilość czasu przed ponowną próbą:

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

Sprawdź swoje aktualne użycie w Dashboardzie, aby zobaczyć swoje limity żądań.

503 Service Unavailable

Objaw: API zwraca status 503.

Przyczyna: Występuje to w dwóch przypadkach:

  1. Osiągnięto limit współbieżności. Masz uruchomionych zbyt wiele jednoczesnych żądań. Różni się to od błędu 429, który ogranicza liczbę żądań na minutę. W przypadku błędu 503 nie przekroczono limitu RPM, ale osiągnięto maksymalną liczbę żądań, które mogą być uruchomione w tym samym czasie.
  2. Usługa tymczasowo wyłączona. Trwa okno serwisowe.

W obu przypadkach odpowiedź zawiera pole retryAfter.

Rozwiązanie: Odczekaj retryAfter sekund, a następnie spróbuj ponownie:

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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Jeśli regularnie trafiasz na limity współbieżności 503, zmniejsz liczbę równoległych requestów w swoim potoku scrapowania lub sprawdź limit współbieżności swojego planu w Dashboardzie.

504 Upstream Timeout

Objaw: API zwraca błąd 504 z {"error": "Upstream timeout"}.

Przyczyna: Praca nie zakończyła się w budżecie czasowym zadeklarowanym dla requestu. Wolny cel, wolne rozwiązanie zabezpieczeń lub bardzo duża strona mogą to spowodować. Nie jest to problem z twoim kluczem, parametrami ani proxy.

Rozwiązanie: Daj wywołaniu więcej czasu lub spróbuj ponownie. FourA czeka na twoje timeout_ms plus mały margines, więc zwiększenie tej wartości realnie wydłuża czas oczekiwania:

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

W przypadku /api/auto/ do chronionego celu, pierwsze wywołanie na zimno może potrwać kilkadziesiąt sekund. Jego timeout_ms obejmuje całą drabinę i akceptuje do 180000.

502 Niedostępny upstream

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

Przyczyna: FourA połączył się z własnym silnikiem, ale nie mógł użyć odpowiedzi, zazwyczaj z powodu restartu instancji.

Rozwiązanie: Ponów próbę z krótkim opóźnieniem. Oba klasyfikują się jako service_error i tylko success podlega opłacie, więc ponowna próba nic Cię nie kosztuje. Jeśli problem trwa dłużej niż minutę lub dwie, sprawdź stronę statusu.

401 Błędy uwierzytelniania

Symptom: Każde żądanie zwraca 401 Unauthorized.

Lista kontrolna:

  1. Sprawdź, czy nagłówek to X-API-Key: YOUR_API_KEY (a nie Authorization: Bearer lub Api-Key)
  2. Sprawdź, czy klucz API nie zawiera dodatkowych spacji lub znaków nowej linii
  3. Utwórz nowy klucz w Panelu, jeśli obecny mógł zostać skompromitowany

400 Cel rozwiązuje się do prywatnego/zastrzeżonego adresu IP

Symptom: API zwraca 400 z Target <ip> resolves to a private/reserved IP, zanim żądanie opuści FourA.

Przyczyna: Twój url rozwiązuje się do prywatnego, pętli zwrotnej (loopback) lub zastrzeżonego zakresu IP (RFC 5735, RFC 6598 lub zastrzeżone bloki IPv6). FourA odrzuca te cele, aby zapobiec użyciu swojej sieci do łączenia się z hostami wewnętrznymi.

Rozwiązanie: Użyj publicznego adresu URL. Jeśli testujesz, użyj celu publicznego, takiego jak https://example.com lub https://httpbin.org/get. Jeśli celem jest Twoja własna usługa, najpierw udostępnij ją pod publiczną nazwą hosta.

{ "error": "Target <ip> resolves to a private/reserved IP" }

no_eligible_proxy podczas używania exitCountries

Objaw: Wywołanie /api/proxy/ z 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: Obecna pula proxy nie zawiera działającego wyjścia, którego kraj widoczny dla celu pasuje do Twojej listy dozwolonych. FourA nigdy nie używa zapasowo nieżądanego kraju po ustawieniu exitCountries.

Rozwiązanie: Zachowaj żądany zakres i spróbuj ponownie później. Pula jest odświeżana mniej więcej co dziesięć minut, więc kraj bez dopasowania obecnie 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 kraju rzeczywiście się zmieniły. Ciche użycie innych krajów jako opcji zapasowej może uszkodzić logikę zależną od geolokalizacji na dalszych etapach.

Ciało odpowiedzi wraca jako zniekształcony tekst

Objaw: Odpowiedź data (lub body) zawiera nieczytelne znaki (mojibake), gdy cel używa kodowania innego niż UTF-8.

Przyczyna: Domyślnie FourA automatycznie dekoduje ciała odpowiedzi do UTF-8 na podstawie nagłówka Content-Type celu lub tagu HTML <meta charset>. Jeśli cel podaje błędne informacje o swoim kodowaniu, otrzymasz zniekształcony tekst.

Rozwiązanie: W przypadku binarnych payloadów (obrazy, protobuf, surowe dane audio), ustaw returnBuffer: true w żądaniu. Ciało zostanie zwrócone jako bufor base64 bez żadnego transkodowania znaków.

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

W przypadku celów tekstowych, które błędnie deklarują swój charset, samodzielnie zdekoduj surowe bajty: pobierz za pomocą returnBuffer: true, zdekoduj z base64, a następnie zastosuj prawidłowy charset.

Nieoczekiwany HTML zamiast JSON

Objaw: Oczekiwano JSON ze strony docelowej, ale otrzymano HTML.

Przyczyna: Strona docelowa może serwować różną treść w zależności od headerów.

Rozwiązanie: Dodaj header Accept i włącz unblocker, aby uzyskać realistyczne headery 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 również ustawić tryJsonData na true, aby FourA automatycznie parsowało odpowiedzi JSON.

Ciało odpowiedzi to strona weryfikacyjna, a nie treść

Symptom: Wywołanie powiodło się, status to 200, ale data (lub body) to weryfikacja bota zamiast żądanej strony.

Przyczyna: Cel uruchomił weryfikację bota, na którą natrafiło FourA, ale nie zdołało jej obejść. Odpowiedź o tym informuje: Single i Proxy zwracają defense z solved: false, a Browser zwraca defenseSolved: false z dostawcą w defenses.present.

Rozwiązanie: Najpierw sprawdź defense.vendor, a następnie eskaluj. Wypróbuj inny profil przeglądarki w Single, przejdź na Proxy dla innego wyjścia lub użyj Browser, aby uruchomić JavaScript. Pełna dokumentacja pól i lista dostawców: Zabezpieczenia Anti-Bot.

Dodaj podciąg validate.data.accept, który zawiera tylko właściwa strona. Bez niego strona weryfikacyjna zwrócona z HTTP 200 jest traktowana jako sukces, a o błędzie dowiadujesz się na dalszym etapie przetwarzania zamiast podczas wywołania.

Nadal masz problem?

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

  1. Sprawdź stronę statusu pod kątem trwających incydentów
  2. Przejrzyj metryki żądań w Panelu
  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: 12 sierpnia 2026