# Błędy API

> URL: https://foura.ai/pl/docs/api/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Jak obsługiwać błędy z FourA API.

## Format odpowiedzi błędu

API zwraca płaskie obiekty JSON dla wszystkich błędów. Nie ma zagnieżdżonego obiektu `error`. Gdy błąd zawiera kod czytelny maszynowo, jest on polem najwyższego poziomu: `reason` przy przekroczeniu limitu planu, `code` przy wywołaniu proxy bez pasującego węzła wyjściowego.

```json
{
  "error": "Invalid API key"
}
```

Niektóre błędy zawierają dodatkowe pola na najwyższym poziomie, takie jak `status`, `service`, `retryAfter`, `current` lub `limits`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

## Śledzenie requesta

Każda response API (sukces lub błąd) zawiera header `X-FourA-Request-Id` z UUID danego wywołania, z wyjątkiem body, którego FourA nie może w ogóle odczytać (niepoprawny JSON lub body powyżej 100 KB): taki request jest odrzucany przed przypisaniem ID. Zapisuj go w logach po swojej stronie. Jeśli będziesz musiał zapytać support o konkretny request, to ID pozwoli nam go odnaleźć.

```bash
curl -i -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://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
```

## Typy błędów

### 400: Bad Request

Treść requesta nie zawiera wymaganych pól, ma nieprawidłowe wartości lub wskazuje cel, którego API odmawia pobrania.

Treść, która nie jest obiektem lub tablicą JSON, jest uznawana za niepoprawny JSON i zwraca kod `Invalid JSON in request body`, jak pokazano poniżej.

W usługach Single, Proxy Finder oraz Browser pole brakujące, o nieprawidłowym typie lub spoza dozwolonego zakresu jest wymieniane w komunikacie jako `<field>: <reason>`. Pola zagnieżdżone są łączone kropkami (`validate.status.accept`). Wymienianych jest do pięciu problemów rozdzielonych separatorem `; `, a jeśli jest ich więcej, komunikat kończy się ciągiem `and <n> more`:

```json
{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}
```

To jest błąd `client_error` i nie podlega rozliczeniu. Auto zgłasza nieobsługiwane pole w odpowiedzi HTTP 200, jak opisano poniżej w sekcji Odczytywanie błędów z `/api/auto/`.

Ten sam kod 400 obejmuje również ochronę przed SSRF. Jeśli Twój `url` rozwiązuje się na prywatny, loopback lub inny zarezerwowany zakres adresów IP (RFC 5735, RFC 6598, zarezerwowane bloki IPv6), request zostanie odrzucony, zanim opuści sieć FourA:

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

`<target>` to adres lub nazwa hosta i adres, na który została rozwiązana. Adres URL, który nie daje się sparsować lub nie jest `http://` ani `https://`, otrzymuje ten sam błąd 400.

Cel wskazujący na własny host API FourA (`eu.api.foura.ai` lub `api.foura.ai`) również otrzymuje błąd 400 w trybach Single, Proxy Finder, Browser oraz Auto, zanim cokolwiek zostanie pobrane lub naliczone. Zwykle oznacza to, że link pobrany ze strony został rozwiązany względem adresu URL API zamiast adresu samej strony:

```json
{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
```

`<url>` to cel dokładnie w takiej postaci, w jakiej go wysłano. Strona [Inspect](https://foura.ai/docs/api/inspect) jest jedynym wyjątkiem: FourA nadal pobiera `https://eu.api.foura.ai/inspect` za Ciebie.

URL ze spacją lub znakiem kontrolnym wewnątrz również zwraca błąd 400 w trybach Single, Proxy Finder i Auto, zanim cokolwiek zostanie pobrane lub naliczone. Link skopiowany ze strony w postaci dosłownej często taki znak zawiera (`javascript: void(0)`, link do udostępniania ze spacjami w tekście). Zakoduj go, spację jako `%20`. Przeglądarka pobiera taki URL tak, jak robi to Chrome:

```json
{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
```

Nazwa hosta, której nie można rozstrzygnąć, nie powoduje odrzucenia żądania. Wywołanie zwraca kod HTTP 200 z `status: 0` oraz powodem (`could not resolve <host>: <reason>`) i nie jest rozliczane. Cel, z którym FourA nawiązuje połączenie, ale nie uzyskuje odpowiedzi HTTP (przekroczenie limitu przekierowań, timeout połączenia lub odczytu, zresetowanie połączenia), również zwraca kod HTTP 200 z `error` oraz `total_time` i bez `status`: zobacz [Request Outcomes](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like).

W planie Single treść odpowiedzi przekraczająca 128 MB po zdekodowaniu zostaje w tym miejscu przerwana. Wywołanie zwraca kod HTTP 200 z `"error": "Response body exceeds the 128 MB limit"` i nie jest rozliczane.

Nieprawidłowo sformatowany kod JSON w treści jest odrzucany w ten sam sposób, przed odczytaniem jakiegokolwiek pola:

```json
{
  "error": "Invalid JSON in request body"
}
```

Pola `proxy` i `ignoreProxies` mają własne błędy 400. Obydwa przyjmują nieprzejrzyste identyfikatory proxy zwrócone przez wcześniejsze odpowiedzi, więc każda inna wartość powoduje błąd dekodowania:

| Komunikat | Co się stało |
|-----------|--------------|
| `Invalid proxy format` | Wartość `proxy` nie jest identyfikatorem proxy wystawionym przez FourA. Wprowadzenie surowego adresu proxy trafia tutaj. |
| `Invalid ignoreProxies format` | Jeden z wpisów w `ignoreProxies` nie jest identyfikatorem proxy. |
| `Proxy not found` | Identyfikator został poprawnie zdekodowany, ale nie wskazuje już na aktywny węzeł wyjściowy. Wybierz nowy. |
| `Managed exit: this proxy id cannot be pinned to a request` | Węzeł wyjściowy istnieje, ale FourA nie utrzyma go otwartego dla wskazanego żądania. Identyfikator węzła premium trafia tutaj, gdy w Twoim planie skończył się transfer premium. Użyj ponownie sesji, w której został zwrócony, lub wyślij wywołanie przez `POST /api/proxy/` i zaakceptuj dowolny wybrany węzeł. |

**Rozwiązanie:** Sprawdź, czy Twoje żądanie zawiera wszystkie wymagane pola, czy adresy URL używają `http://` lub `https://` ze spacjami zakodowanymi jako `%20`, czy host jest tłumaczony na adres publiczny oraz czy każda wartość `proxy` jest identyfikatorem skopiowanym dosłownie z wcześniejszej odpowiedzi.

Są to wyniki typu `client_error`: żądanie nigdy nie opuściło FourA, więc żadne środki ani limity nie zostały zużyte.

### 401: Unauthorized

Twój klucz API jest nieprawidłowy lub go brakuje.

Brakujący klucz:

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

Nieprawidłowy klucz:

```json
{
  "error": "Invalid API key"
}
```

**Rozwiązanie:** Sprawdź, czy nagłówek `X-API-Key` zawiera poprawny klucz. W razie potrzeby wygeneruj nowy klucz w [Panelu](https://foura.ai/dashboard).

Kod 401 oznacza zawsze, że usługa FourA zweryfikowała Twój klucz i go odrzuciła. Gdy FourA nie może zweryfikować klucza przez kilka sekund, zwraca kod 503 `API key check temporarily unavailable` (patrz poniżej), nigdy 401.

### 403: Poza Twoim planem

Żądanie dotyczyło endpointu lub parametru, którego nie obejmuje Twój plan. Odpowiedź ustawia `X-FourA-Limit` i umieszcza ten sam kod w treści pod kluczem `reason`:

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

`reason` ma wartość `plan_limit_feature` w przypadku endpointu nieuwzględnionego w planie lub dla `exitCountries` oraz pól lokalizacji wyjściowej w planie bez targetowania geograficznego, a także `plan_limit_premium` dla `exitClass: premium` w planie bez wyjść premium lub dla [lokalizacji wyjściowej](https://foura.ai/docs/api/endpoints#exit-location) bez pozostałego ruchu premium. Ciąg `error` wskazuje nazwę endpointu lub parametru.

Kod 403 z FourA nigdy nie dotyczy witryny docelowej: z celem w ogóle się nie skontaktowano. Kod 403 zwrócony przez cel dociera jako HTTP 200 z `status: 403` w treści odpowiedzi.

**Rozwiązanie:** Usuń parametr, wywołaj endpoint zawarty w Twoim planie lub zmień plan na wyższy. Nagłówek `Retry-After` nie jest ustawiany, ponieważ oczekiwanie nie zmieni wyniku. Żadne środki nie zostały zużyte: wynik to `rate_limit`, a rozliczany jest wyłącznie stan `success`.

### 413: Ładunek zbyt duży

Treść żądania JSON przekracza limit akceptowany przez FourA (100 KB). Odpowiedź nie jest w formacie JSON i nie zawiera `X-FourA-Request-Id`, ponieważ treść jest odrzucana przed jej odczytaniem.

**Rozwiązanie:** Wyślij mniejszy ładunek `data`. Żadne środki nie zostały zużyte.

### 429: Limit zapytań przekroczony

Dwie różne weryfikacje odpowiadają kodem 429 i nie zwracają one tych samych pól.

**Własne limity Twojego planu.** W odpowiedzi ustawiany jest nagłówek `X-FourA-Limit` określający, który limit odrzucił wywołanie, a ten sam kod umieszczany jest w treści pod kluczem `reason`:

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

`reason` to jeden z `plan_limit_concurrency`, `plan_limit_rate`, `plan_limit_browser_daily`, `plan_limit_credits` lub `plan_limit_bandwidth`. Gdy oczekiwanie pomaga, czas oczekiwania znajduje się w `retry_after_seconds` oraz w nagłówku `Retry-After`, nigdy w `retryAfter`. `plan_limit_browser_daily` nie zawiera żadnego z nich, ponieważ limit odnawia się o północy UTC, a nie w sekundach. Nic nie zostało wykorzystane: wynikiem jest `rate_limit`, a rozliczane jest wyłącznie `success`.

**Współdzielony limit platformy.** Brak nagłówka `X-FourA-Limit`, a czas oczekiwania znajduje się w `retryAfter`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`current` i `limits` opisują usługę dla całego ruchu, a nie Twojego konta. Odrzucenie tutaj oznacza, że FourA jest przeciążone.

**Rozwiązanie:** Odczekaj czas wskazany w `Retry-After`, `retry_after_seconds` lub `retryAfter`, zależnie od tego, który nagłówek zawiera response. W przypadku limitu współbieżności lub rate limitu ogranicz liczbę otwartych requestów zamiast ponawiać całą odrzuconą serię. W przypadku limitu dziennego lub okresu rozliczeniowego zatrzymaj wykonywanie. Zobacz [Rate Limits](https://foura.ai/docs/api/rate-limits), aby poznać wszystkie pola, oraz [Równoległe wykonywanie requestów](https://foura.ai/docs/how-to/run-requests-in-parallel), aby poznać właściwy wzorzec.

### 500: Błąd serwera

Coś poszło nie tak po naszej stronie.

**Rozwiązanie:** Ponów request po krótkim opóźnieniu. Jeśli błąd nadal występuje, sprawdź [stronę ze statusem](https://updates.foura.ai/status) lub skontaktuj się ze wsparciem, podając `X-FourA-Request-Id` z nieudanego response.

### 502: Serwis nadrzędny niedostępny

FourA nie mogło uzyskać odpowiedzi od własnego silnika (`Upstream unavailable`: połączenie nie powiodło się) lub otrzymało odpowiedź, której nie mogło odczytać (`Malformed JSON from backend`).

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**Rozwiązanie:** Ponów próbę z krótkim wyczekiwaniem. Problem leży po naszej stronie, więc nic Cię to nie kosztuje: wynikiem jest `service_error` i naliczana jest opłata tylko za `success`.

### 504: Przekroczenie limitu czasu serwera nadrzędnego

Silnik nie zakończył pracy w przewidzianym budżecie czasu dla tego żądania.

```json
{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}
```

Błąd 504 dotyczy czasu trwania operacji, a nie Twojego klucza, parametrów czy proxy. Najczęstsze przyczyny to wolno odpowiadające cele, rozwiązywanie challenge'y przy zimnym starcie oraz duże strony.

**Rozwiązanie:** Zwiększ `timeout_ms` w request (Single przyjmuje do 120000, Browser do 120000, Auto do 180000) lub ponów próbę. FourA czeka przez zadeklarowany limit czasu powiększony o niewielki margines, więc żądanie dłuższego czasu rzeczywiście go wydłuża.

### 503: Usługa wyłączona lub brak wolnych zasobów

Błąd 503 oznacza, że usługa jest tymczasowo niedostępna z powodu prac konserwacyjnych lub wyczerpał się limit współbieżności platformy. Obie formy zawierają te same klucze: `error`, `status`, `service`, `retryAfter`, `current` oraz `limits`. Rozróżniaj je na podstawie ciągu `error`, a nie obecności konkretnych pól.

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`Service disabled` oznacza przerwę techniczną, a `current` zwraca `0` dla obu liczników, ponieważ request został odrzucony przed wykonaniem jakichkolwiek pomiarów. `Service at capacity` dotyczy limitu współbieżności, gdzie `current` zawiera rzeczywiste użycie platformy. Zobacz [Rate Limits](https://foura.ai/docs/api/rate-limits), aby poznać tę strukturę.

**Rozwiązanie:** Odczekaj `retryAfter` s i ponów próbę. Strona ze statusem zawiera listę aktywnych okien serwisowych.

Trzeci wariant błędu 503 nie zawiera `retryAfter`. Oznacza on, że silnik obsługujący dany endpoint nie mógł przyjąć wywołania: był restartowany, wystąpił błąd po stronie FourA przed uruchomieniem requestu lub (w przypadku Browser) wszystkie przeglądarki były zajęte przez 10 sekund oczekiwania strony na dostępność. `backend_status` to własny status silnika, a `detail` to początek jego odpowiedzi:

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}
```

To błąd `service_error`, który nie podlega opłacie. Ponów próbę po sekundzie lub dwóch. Błędny sam w sobie request nigdy tu nie trafia: otrzymuje kod 400 wskazujący konkretne pole.

Czwarty wariant 503 oznacza, że FourA chwilowo nie mogło potwierdzić Twojego klucza API, na przykład podczas przełączania bazy danych. Twój klucz jest prawidłowy i nic nie zostało uruchomione. Zwraca `Retry-After: 5` oraz ten sam czas oczekiwania w `retryAfter`:

```json
{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}
```

To żądanie nie jest rozliczane. Ponów próbę po `retryAfter` s. Klucz potwierdzony przez FourA w ciągu ostatnich 10 minut nadal działa w takich sytuacjach, więc ta odpowiedź pojawia się rzadko.

## Odczytywanie błędów z `/api/auto/`

`POST /api/auto/` odpowiada kodem HTTP 200 zawsze, gdy sekwencja ladder została uruchomiona, nawet jeśli każdy krok zakończył się niepowodzeniem. Rzeczywisty wynik znajduje się w treści odpowiedzi:

```json
{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
```

`status` to ostatni status zwrócony przez cel lub 502, gdy żadna próba do niego nie dotarła (504, gdy wcześniej wyczerpał się limit czasu). Każda nieudana odpowiedź z wykonanej sekwencji zawiera również `attemptReport` zliczający napotkane problemy, jednolinijkowy `summary` bezpieczny do logowania, a `meta.attemptsByEngine` oraz `meta.browserRequests` wskazują, co wysłało wywołanie. Zobacz [Dlaczego wywołanie Auto nie powiodło się](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed). Pole żądania nieobsługiwane przez Auto (na przykład `timeout_ms` poniżej 5000 lub powyżej 180000) jest zwracane w ten sam sposób: HTTP 200 z `"status": 400` i przyczyną w `error`, przed podjęciem jakiejkolwiek próby i bez naliczania kosztów.

Nie rozgałęziaj więc logiki na podstawie statusu transportowego dla Auto. Zamiast tego odczytaj `status` i `error` z treści odpowiedzi. Rzeczywisty kod różny od 200 z `/api/auto/` oznacza, że FourA odrzuciło wywołanie przed uruchomieniem sekwencji lub nie mogło go dokończyć: 400 (nieprawidłowy JSON, prywatny lub zarezerwowany cel albo cel na hoście API FourA), 401, 413, 502, 503 lub 504. Jeden limit planu jest weryfikowany na wejściu: `exitClass: premium` w planie bez węzłów wyjściowych premium otrzymuje 403 z `X-FourA-Limit: plan_limit_premium`, zanim zostaną wykonane jakiekolwiek działania. Wszystkie inne limity, Twoje lub platformy, wracają w ramach odpowiedzi 200 ze statusem w treści.

Gdy witryna odrzuci kilka wywołań Auto z rzędu dla danego klucza API, Auto przez pewien czas odpowiada na kolejne wywołania natychmiast, bez ponawiania prób: `"error": "target temporarily unservable, retry later"`, `"status": 503` oraz `retryAfter` w sekundach. Nie generuje to kosztów; odczekaj `retryAfter` s.

Limit planu napotkany przez jedno z podwywołań również wraca jako HTTP 200. Treść stanowi samo odrzucenie z odpowiednim `reason` wraz z `status` i `meta`, a odpowiedź zawiera ten sam nagłówek `X-FourA-Limit`, co bezpośrednia odmowa:

```json
{
  "status": 429,
  "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",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

Kwestia tego, które limity zatrzymują całą sekwencję, a które zamykają tylko dany stopień, została opisana w sekcji [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## Błędy po stronie celu wewnątrz 200 OK

Nie każdy błąd objawia się statusem HTTP innym niż 2xx. Gdy cel zwraca HTTP 200, ale odpowiedź FourA zawiera `error` (na przykład Twoje reguły `validate` odrzuciły treść) lub treść jest stroną weryfikacyjną rozpoznawaną przez FourA, wynikiem jest `application_error`. Gdy cel zwraca status inny niż 200, którego nie akceptują Twoje reguły `validate`, wynikiem jest `application_fail`, a treść jest przekazywana bez zmian.

Żaden z tych przypadków nie podlega opłacie: rozliczany jest wyłącznie `success`. Wywołanie Browser, które zastanie wszystkie przeglądarki zajęte, czeka do 10 sekund na zwolnienie zasobu. Jeśli żaden się nie zwolni, zwracany jest błąd 503 `Backend service unavailable` opisany powyżej. Browser może również odpowiedzieć statusem HTTP 200 z `"error": "No available browser slot"`, gdy w ogóle nie udało się uzyskać instancji przeglądarki. Żaden z tych przypadków nie jest fakturowany. Ponów próbę po kilku sekundach lub utrzymuj mniej równoległych wywołań Browser jednocześnie. Kompletna taksonomia znajduje się w dokumentacji [Outcomes](https://foura.ai/docs/api/outcomes).

Pojedyncze wywołanie przez przypięty węzeł `proxy` może również zwrócić HTTP 200 z `"error": "The exit gave the same answer for <n> different sites"` obok treści. FourA wykryło, że dany węzeł wyjściowy serwuje tę samą stronę dla niepowiązanych witryn, więc strona pochodzi od samego węzła wyjściowego, a nie z docelowego adresu. Zwracany jest status `application_error` i nie jest on rozliczany. Pobierz nowy węzeł wyjściowy z `POST /api/proxy/`, który automatycznie pomija takie węzły.

To samo dotyczy sytuacji, gdy zamiast witryny odpowiada sieć węzła wyjściowego. Wywołanie zwraca `"error": "The exit answered instead of the site (<name>)"` lub `"error": "Corporate web gateway intercepted the request (<name>)"` (stronę logowania, filtrowania lub przekierowanie do niej), `"error": "The exit intercepted TLS and answered instead of the site (<name>)"`, gdy węzeł wyjściowy odpowiedział w imieniu samej witryny, lub `"error": "Honeypot echo proxy (plaintext request dump)"`, gdy węzeł wyjściowy odesłał kopię Twojego własnego żądania. FourA weryfikuje te sytuacje niezależnie od Twoich reguł `validate`, wliczając pobieranie `returnBuffer`. Żadna z nich nie podlega opłacie. Pobierz nowy węzeł wyjściowy w ten sam sposób.

## Kodowanie odpowiedzi

FourA automatycznie dekoduje treść odpowiedzi do UTF-8. Jeśli cel zwraca `windows-1251`, `gbk`, `shift_jis`, `iso-8859-*` lub dowolny inny zestaw znaków zadeklarowany w nagłówku `Content-Type` albo tagu HTML `<meta charset>`, otrzymujesz poprawny ciąg znaków UTF-8 w polu `data` (single, proxy) lub `body` (browser).

Dla ładunków binarnych (obrazy, protobuf, surowe audio) 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.

## Strategia ponawiania prób

Praktyczna polityka ponawiania prób:

```python
import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")
```

## Błędy proxy zawierają raport

Wywołanie `POST /api/proxy/`, które wyczerpie limit prób, zwraca HTTP 200 z kopertą błędu, a nie kod błędu HTTP. Ciąg błędu jest krótki i ma zawsze taki sam format, dlatego obiekt `attemptReport` jest dołączony obok niego wraz z licznikami:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

Zapisuj `attemptReport.summary` w logach obok błędu, a dowiesz się, czy węzły wyjściowe były zablokowane, nieaktywne, czy zwracały strony odrzucone przez Twoje własne reguły `validate`. Opis pól i zalecane działania dla poszczególnych wartości: [Dlaczego żądanie proxy wyczerpało limit prób](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

## Powiązane

- [Rate limity](https://foura.ai/docs/api/rate-limits): Limity planu, współbieżność i szczegóły RPM
- [Równoległe wykonywanie żądań](https://foura.ai/docs/how-to/run-requests-in-parallel): Utrzymywanie limitu współbieżności planu
- [Wyniki żądań](https://foura.ai/docs/api/outcomes): Wyjaśnienie siedmiu wartości wyników
- [Typowe problemy](https://foura.ai/docs/troubleshooting/common-issues): Objawy, przyczyny, rozwiązania
- [Weryfikacje witryny](https://foura.ai/docs/api/site-checks): Gdy treść odpowiedzi to strona typu challenge zamiast błędu
- [Dlaczego żądanie proxy wyczerpało limit prób](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Odczytywanie `attemptReport`
