# Dokumentacja endpointów API

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

Dokumentacja referencyjna wszystkich endpointów FourA API z parametrami requestów i formatami response.

## Bazowy URL

```
https://eu.api.foura.ai/api
```

## Uwierzytelnianie

Każde request wymaga Twojego klucza API w headerze `X-API-Key`:

```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://example.com"}'
```

Twórz klucze API i zarządzaj nimi w [Dashboardzie](https://foura.ai/dashboard). Klucze używają prefiksu `pk_live_`.

## Nagłówki odpowiedzi

Odpowiedzi z `/api/*` zawierają dwa nagłówki korelacji:

| Nagłówek | Wartość | Opis |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | Unikalny identyfikator przypisany do żądania. Zwracany w każdej odpowiedzi, w tym 4xx i 5xx, z wyjątkiem treści, których FourA nie może w ogóle odczytać: `400 Invalid JSON in request body` i `413` są odrzucane przed przypisaniem identyfikatora. Zapisuj go w logach po swojej stronie. |
| `X-FourA-Credits` | integer | Kredyty wykorzystane na to żądanie. Zwracany w każdej odpowiedzi, która dotarła do silnika, zarówno zakończonej sukcesem, jak i niepowodzeniem (praca została wykonana w obu przypadkach). Wywołanie, które FourA odrzuci przed uruchomieniem silnika (brakujący lub nieprawidłowy klucz, limit planu lub platformy, odrzucony cel lub proxy ID), nie zawiera tej wartości. Zobacz [Wyniki żądań](https://foura.ai/docs/api/outcomes), aby sprawdzić, które wyniki podlegają rozliczeniu. |

Ten sam identyfikator żądania indeksuje podgląd payloadu żądania i odpowiedzi w sekcji Dashboardu [Activity Log](https://foura.ai/docs/dashboard/activity-log) (przechowywane przez 24 godziny, ostatnie 200 na klucz), dzięki czemu możesz sprawdzić dokładne żądanie później i odtworzyć je z poziomu Activity bezpośrednio w [Playgroundzie](https://foura.ai/docs/dashboard/playground). Dołącz go przy kontakcie z pomocą techniczną, aby zlokalizować żądanie w kilka sekund.

```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/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...
```

Zobacz [Response Headers](https://foura.ai/docs/api/response-headers), aby sprawdzić pełną listę i wskazówki dotyczące użycia.

## Punkty końcowe

> **Korzystasz z tych punktów końcowych przez MCP?** Serwer [`@fouradata/mcp`](https://foura.ai/docs/mcp/server) udostępnia wszystkie cztery punkty końcowe jako natywne narzędzia MCP (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) z takimi samymi formatami danych wejściowych oraz opcją `offload_large` pozwalającą na oszczędzanie tokenów przy dużych odpowiedziach. Różnice: `foura_browser` nie ma pola `lean`, a `foura_proxy` nie obsługuje jeszcze pól [exit location](#exit-location).

FourA oferuje cztery punkty końcowe zapytań, każdy zoptymalizowany pod kątem innego scenariusza:

| Punkt końcowy | Najlepszy do |
|----------|----------|
| `POST /auto/` | Inteligentne pobieranie. Podajesz URL, a FourA wybiera najtańszą działającą ścieżkę (rotowane proxy lub przeglądarkę oraz bezpośrednie zapytanie z `forceProxy: false`) i zapamiętuje, co działa dla danego hosta. |
| `POST /single/` | Szybkie zapytania HTTP, strony statyczne, interfejsy API |
| `POST /proxy/` | Chronione witryny z automatyczną rotacją proxy, opcjonalny wybór kraju widocznego dla celu |
| `POST /browser/` | Strony renderowane przez JavaScript, SPA |
| `GET /profiles` | Katalog profili przeglądarek dla `single` i `proxy`. Publiczny, bez klucza API. |

Więcej szczegółów na temat wyboru odpowiedniego rozwiązania znajdziesz w sekcjach [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type) oraz w przewodniku [Smart Fetch guide](https://foura.ai/docs/guides/smart-fetch).

## Ograniczenia docelowych adresów URL

Cele wskazujące na prywatne, pętli zwrotnej lub zastrzeżone pule adresów IP (RFC 5735, RFC 6598, zastrzeżone bloki IPv6) są odrzucane z kodem 400, zanim zapytanie opuści FourA. Przekazywane są wyłącznie publiczne nazwy hostów i adresy IP.

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

Cel wskazujący na własny host API FourA (`eu.api.foura.ai` lub `api.foura.ai`) jest również odrzucany z kodem 400 na wszystkich czterech endpointach, zanim cokolwiek zostanie pobrane lub naliczone. Adres URL zawierający spację lub znak sterujący jest odrzucany z kodem 400 w trybach Single, Proxy oraz Auto w ten sam sposób; zakoduj spację jako `%20` (Browser pobiera go tak, jak Chrome). Jedyną stroną pobieraną tam przez FourA jest [`/inspect`](https://foura.ai/docs/api/inspect).

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

---

## Smart Fetch (Auto)

`POST /api/auto/`

Przekazujesz URL oraz opcjonalne reguły `validate`. FourA przechodzi przez zoptymalizowaną pod kątem kosztów ścieżkę (rotowany proxy, następnie pełna przeglądarka) i zatrzymuje się na pierwszym poziomie, który zwróci response zaakceptowany przez Twoje reguły. Przy `forceProxy: false` najpierw wykonywana jest tania próba bezpośrednia. Przy kolejnych wywołaniach do tego samego hosta odtwarzana jest rozgrzana sesja, dzięki czemu drugie trafienie jest tanie.

Nie musisz konfigurować ponownych prób, rozmiarów pul ani liczby proxy. FourA uczy się ich dla każdego hosta.

### Request Body

| Parametr | Typ | Wymagany | Domyślnie | Opis |
|-----------|------|----------|---------|-------------|
| `url` | string | Tak | - | Docelowy URL |
| `method` | string | Nie | `"GET"` | Metoda HTTP |
| `headers` | [string, string][] | Nie | - | Nagłówki do wysłania do celu jako pary [name, value]. Wysyła je każdy poziom z wyjątkiem poziomu przeglądarki. Wysłany `Cookie` trafia do witryny bez zmian, a pliki cookie z zapisanej sesji są dodawane obok niego wyłącznie pod nazwami, których nie przesłano. `userAgent` z zapisanej sesji zastępuje Twój `User-Agent`. Poziom proxy pomija nagłówki warunkowe, takie jak `If-None-Match`, chyba że Twój `validate.status.accept` zawiera `304`. |
| `data` | any | Nie | - | Treść request dla metod innych niż GET |
| `validate` | object | Nie | - | Kryteria sukcesu, o takiej samej strukturze jak `validate` w Single Request (patrz poniżej). Określ dla trybu auto, jak wygląda właściwa strona, aby odróżnić treść od strony z wyzwaniem. |
| `returnSession` | boolean | Nie | `true` | Dołącz zwycięską sesję (`proxy`, `cookies`, `userAgent`) do response, aby umożliwić jej ponowne użycie przez `/api/single/` lub `/api/browser/`. |
| `forceProxy` | boolean | Nie | `true` | Zawsze kieruj ruch przez rotowany proxy. Ustaw `false`, aby zezwolić na tańszą ścieżkę bezpośrednią, gdy cel na to pozwala (niektóre mechanizmy obronne są bardziej rygorystyczne wobec ruchu z proxy). |
| `timeout_ms` | integer | Nie | `120000` | Całkowity budżet czasowy na całe wywołanie w milisekundach. Wszystkie próby cząstkowe mieszczą się w tym budżecie. Min. `5000`, maks. `180000`. |
| `ignoreProxies` | string[] | Nie | - | Identyfikatory proxy do pominięcia przy każdej próbie cząstkowej. Użyj identyfikatorów zwróconych przez wcześniejsze response `/api/auto/` lub `/api/proxy/`. |
| `followRedirects` | integer | Nie | `5` | Maksymalna liczba przekierowań do obsłużenia na niższych poziomach ścieżki. `0` wyłącza przekierowania. Maks. `20`. |
| `exitClass` | string | Nie | - | `standard` lub `premium`, tak jak w [Proxy Request](#exitclass). `premium` pozwala eskalować wywołanie do węzła premium, gdy standardowa pula nie może uzyskać dostępu do strony. Wymaga planu zawierającego węzły premium. Zobacz [exitClass w Smart Fetch](#exitclass-on-smart-fetch). |

### Response

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
```

| Pole | Typ | Opis |
|-------|------|-------------|
| `status` | number | Status HTTP z celu. |
| `data` | string | Ciało response jako tekst, niezależnie od poziomu drabiny, który je obsłużył. Strona JSON wraca jako tekst JSON, więc parsujesz ją samodzielnie. |
| `headers` | array or object | Nagłówki response z celu. Poziomy pojedyncze i proxy zwracają tablicę obiektów nagłówków dla każdego przeskoku; poziomy przeglądarkowe zwracają płaski obiekt. |
| `meta.rung` | string | Który poziom drabiny dostarczył response. Jeden z: `probe` (tani request bezpośredni, tylko z `forceProxy: false`), `proxy` (rotujące proxy), `browser` (pełne renderowanie w przeglądarce), `cache` (odtworzona rozgrzana sesja), `warmup` (strona wejściowa witryny została pobrana jako pierwsza, a jej cookie otworzyły głęboki URL) lub `fail` (żaden poziom nie wygenerował zaakceptowanego response). |
| `meta.solved` | boolean | Czy strona wymagała dodatkowego kroku (strony wyzwania / challenge) i został on ukończony podczas tego wywołania. |
| `meta.attempts` | number | Podpróby wykonane przed sukcesem. |
| `meta.credits` | number | Łączna liczba kredytów zużytych na to wywołanie. Odpowiada `X-FourA-Credits`. |
| `meta.attemptsByEngine` | object | Requesty wysłane do `single`, `proxy` i `browser`. Request przeglądarkowy odrzucony przez Twój plan wlicza się, ponieważ został wysłany. |
| `meta.browserRequests` | number | Requesty przeglądarkowe, które zajęły slot z Twojego dziennego limitu. Request przeglądarkowy odrzucony przez Twój plan nie zużywa nic. |
| `meta.exitClass` | string | Jaka klasa wyjścia dostarczyła odpowiedź, obecne gdy request określał `exitClass`: `premium` lub `standard`. Ta sama wartość jest przesyłana w nagłówku response `X-FourA-Exit-Class`. |
| `session.proxy` | string | Zakodowany ID proxy, które dostarczyło response. Użyj go ponownie w requeście Single lub Browser. Obecne, gdy `returnSession` to `true`. |
| `session.cookies` | array | Cookie do odtworzenia, każde zawierające co najmniej `name` i `value`. Poziom przeglądarkowy zwraca cookie jar przeglądarki. Poziom proxy lub bezpośrednia próba zwraca tylko te cookie, które otworzyły stronę (np. ustawione przez stronę weryfikacyjną witryny), a nie wszystkie cookie ustawione przez stronę, więc lista może być pusta. Obecne, gdy `returnSession` to `true`. |
| `session.userAgent` | string | User-Agent użyty podczas udanej próby. Obecne, gdy `returnSession` to `true`. |
| `error` | string | Komunikat błędu, jeśli wywołanie się nie powiodło. |
| `attemptReport` | object | Przy nieudanym wywołaniu: requesty silnika, które wróciły bez strony, pogrupowane według przyczyny. Zobacz [Smart Fetch](https://foura.ai/docs/guides/smart-fetch). |

### Przykład

```bash
curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'
```

### Uwagi

- Auto działa jako koordynator. Wywołuje wewnętrznie Single, Proxy lub Browser i przekazuje Twój klucz API do każdego podwywołania. Wywołanie Auto to jedno żądanie w Twoim [Activity Log](https://foura.ai/docs/dashboard/activity-log) oraz w Overview, z sumą kredytów jego podwywołań; podwywołania są wymienione pod nim jako próby i nigdy nie liczą się jako osobne żądania.
- Przekaż `validate.data.accept` z podciągiem znaków, który zawiera tylko prawdziwa strona. Bez tego auto nie odróżni prawdziwego 200 od strony z wyzwaniem zwróconej ze statusem 200.
- Usunięta strona jest odpowiedzią witryny, a nie odmową. Gdy dwa węzły wyjściowe zwrócą ten sam kod `404` lub `410`, a Twoja `validate` go nie akceptuje, wywołanie kończy się tym statusem `status` i nagłówkiem `error` rozpoczynającym się od `the site answered`. Podaj ten status w `validate.status.accept`, a Auto zwróci pierwszą odpowiedź z tym statusem, która spełnia pozostałe warunki Twojej `validate`. To samo dotyczy każdego innego podanego tam statusu, z wyjątkiem `403`, `429`, `503` i `202`, które witryny wysyłają również ze stroną wyzwania.
- `timeout_ms` ogranicza całe wywołanie. Pierwsze, zimne wywołanie chronionej witryny może zająć kilkadziesiąt sekund; ponownie użyte, rozgrzane sesje kończą się zwykle w czasie poniżej sekundy.

### exitClass w Smart Fetch

`exitClass` działa w Smart Fetch tak samo jak w [Proxy Request](#exitclass): jako zezwolenie, a nie polecenie. Auto najpierw próbuje standardowej puli. Gdy standardowa pula nie może dotrzeć do strony, a żądanie wskazuje `premium`, Auto otwiera stronę w przeglądarce przez węzeł wyjściowy premium. Utworzona w ten sposób sesja obsługuje Twoje późniejsze wywołania do tej samej witryny, które również wskazują `premium`; wywołania, które go nie wskazują, nigdy z niej nie korzystają.

Wyczerpanie limitu nie jest błędem. Gdy ruch premium w Twoim planie zostanie wyczerpany w danym okresie rozliczeniowym, wywołanie jest kontynuowane w standardowej puli, a `meta.exitClass` zwraca `standard`. W planie bez węzłów wyjściowych premium wywołanie wysyłające `exitClass: premium` jest odrzucane z kodem `403` zawierającym `X-FourA-Limit: plan_limit_premium`, zanim zostanie wykonana jakakolwiek praca.

Ruch premium jest mierzony tak samo jak w Proxy Request. Strona otwarta w przeglądarce ładuje więcej niż samą stronę, dlatego strona premium Smart Fetch zużywa więcej ruchu premium niż ta sama strona pobrana przez Proxy Request. Aby to ograniczyć, strona premium Smart Fetch ładuje się bez obrazów, czcionek i multimediów oraz bez skryptów od znanych dostawców reklam, analityki i zgód.

---

## Single Request

`POST /api/single/`

Wysyła żądanie HTTP z realistycznymi, zbliżonymi do przeglądarki charakterystykami sieciowymi, bez uruchamiania prawdziwej przeglądarki. To najszybszy endpoint.

### Request Body

| Parametr | Typ | Wymagany | Domyślnie | Opis |
|-----------|------|----------|---------|-------------|
| `method` | string | Tak | - | Metoda HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | Tak | - | Docelowy URL. Użyj `{ts}` w dowolnym miejscu adresu URL, aby wstawić bieżący znacznik czasu w celu ominięcia pamięci podręcznej. |
| `headers` | [string, string][] | Nie | - | Niestandardowe nagłówki jako pary [nazwa, wartość] |
| `unblocker` | boolean | Nie | `true` | Wysyłaj realistyczne nagłówki przeglądarki (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Domyślnie włączone. Ustaw `false`, a FourA nie doda żadnych nagłówków przeglądarki, tylko te przekazane przez Ciebie. |
| `timeout_ms` | number | Nie | 15000 | Całkowity limit czasu w ms (maks.: 120000) |
| `connect_timeout_ms` | number | Nie | 5000 | Limit czasu połączenia w ms |
| `accept_timeout_ms` | number | Nie | 5000 | Limit czasu akceptacji w ms (czas oczekiwania na zaakceptowanie połączenia) |
| `server_response_timeout_ms` | number | Nie | 15000 | Limit czasu odpowiedzi serwera w ms (czas oczekiwania na pierwszy bajt) |
| `dns_cache_timeout_sec` | number | Nie | 120 | TTL pamięci podręcznej DNS w sekundach (maks.: 240) |
| `followRedirects` | number | Nie | wyłączone | Maksymalna liczba przekierowań do wykonania (0-20). Pomiń, aby wyłączyć. |
| `tryJsonData` | boolean | Nie | false | Parsuj treść odpowiedzi jako JSON, jeśli to możliwe |
| `returnBuffer` | boolean | Nie | false | Zwróć surowy bufor zamiast zdekodowanego ciągu znaków |
| `data` | any | Nie | - | Treść żądania (ciąg znaków lub obiekt, automatycznie serializowany do JSON) |
| `proxy` | string | Nie | - | Identyfikator proxy z wcześniejszej odpowiedzi, aby przypiąć ten sam węzeł wyjściowy. Przekaż nieprzezroczysty ciąg znaków dosłownie. Surowy adres proxy jest odrzucany z błędem `400 Invalid proxy format`. Niektórych identyfikatorów nie można przypiąć: zobacz [Pinning an exit](#pinning-an-exit). |
| `browser` | string | Nie | Chrome | Przeglądarka do symulacji: Chrome, Edge, Safari, Firefox lub Tor. Zobacz [Browser profiles](#browser-profiles). |
| `os` | string | Nie | - | System operacyjny do symulacji: Windows, macOS, Android lub iOS. Nazwa rodziny akceptuje dowolną z jej wersji. |
| `version` | string | Nie | newest | Wersja przeglądarki do symulacji, zgodnie z katalogiem. W przypadku wielu pasujących wersji wybierana jest najnowsza. |
| `profile` | string | Nie | - | Dokładny identyfikator profilu z `GET /api/profiles`, zamiast trzech powyższych pól. |
| `validate` | object | Nie | - | Reguły walidacji odpowiedzi (patrz poniżej) |

### Profile przeglądarek

Domyślnie żądanie symuluje najnowszą wersję Google Chrome. Niektóre cele akceptują jedną przeglądarkę, a odrzucają inną, dlatego `browser`, `os` i `version` zawężają katalog zmierzonych profili, a `profile` wybiera profil według identyfikatora.

```json
{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}
```

Zasady:

- Wybór wymaga `unblocker` (domyślnie włączone). Przy wyłączonym `unblocker` nagłówki przeglądarki nie są wysyłane, więc request jest odrzucany zamiast częściowo zastosowany.
- Gdy pasuje kilka profili, wybierana jest najnowsza wersja.
- Kombinacja niedostępna w katalogu zwraca błąd ze wskazaniem dostępnych opcji, a nieznany identyfikator `profile` zwraca `unknown profile '<id>'`. Request nigdy nie jest wysyłany jako inna przeglądarka.
- Te same cztery pola są dostępne wewnątrz obiektu `request` w `POST /proxy/`.

`GET /api/profiles` zwraca pełny katalog i nie wymaga klucza API:

```json
{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}
```

`osFamily` to wartość używana do filtrowania podczas tworzenia selektora; `os` zachowuje nazwę wydania do wyświetlenia.

### Reguły walidacji

Obiekt `validate` pozwala zdefiniować warunki sukcesu i błędu. Jeśli warunek `fail` zostanie spełniony, żądanie jest traktowane jako nieudane. Jeśli warunki `accept` są ustawione, tylko pasujące odpowiedzi są traktowane jako udane.

```json
{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
```

| Pole | Typ | Opis |
|-------|------|-------------|
| `validate.status.accept` | number[] | Kody statusu HTTP do zaakceptowania |
| `validate.status.fail` | number[] | Kody statusu HTTP do odrzucenia |
| `validate.headers.accept` | object | Odpowiedź jest poprawna, gdy co najmniej jedna para pasuje na dowolnym etapie przekierowania. Nazwy i wartości są dopasowywane bez uwzględniania wielkości liter, na podstawie fragmentu tekstu. |
| `validate.headers.fail` | object | Pary klucz-wartość nagłówka, które powodują niepowodzenie |
| `validate.data.accept` | string[] | Odpowiedź jest poprawna, gdy treść zawiera co najmniej jeden z tych ciągów znaków |
| `validate.data.fail` | string[] | Ciągi znaków w treści odpowiedzi, które powodują niepowodzenie |

### Przykład

```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://example.com/products",
    "timeout_ms": 10000
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}
```

Gdy cel uruchamia weryfikację bota przed zwróceniem treści, response zawiera również obiekt `defense` ze wskazaniem dostawcy oraz informacją, czy weryfikacja zakończyła się powodzeniem:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
```

| Pole | Typ | Opis |
|-------|------|-------------|
| `status` | number | Kod statusu HTTP z serwera docelowego |
| `headers` | array | Jeden obiekt na każdy przeskok przekierowania. Każdy zawiera pole `result` z linią statusu oraz wszystkimi nagłówkami odpowiedzi. Nagłówki wielowartościowe (`Set-Cookie`, `Link`, `WWW-Authenticate`) są zwracane jako tablice ciągów znaków. |
| `data` | string/object | Ciało odpowiedzi (JSON, jeśli `tryJsonData` ma wartość true) |
| `total_time` | number | Całkowity czas żądania w sekundach |
| `proxy` | string | Zakodowany identyfikator proxy, przez który przeszło żądanie (tylko wtedy, gdy w żądaniu podano `proxy`). Użyj go ponownie w kolejnym wywołaniu, aby przypiąć ten sam węzeł wyjściowy. |
| `defense` | object | Obecne, gdy cel wykonał weryfikację bota dla tego żądania lub gdy ponowna próba z własnymi plikami cookie witryny zwróciła treść. `defense.solved` wskazuje, czy weryfikacja zakończyła się sukcesem, a `defense.retry` określa, czy ponowienie dostarczyło zawartość. Zobacz [Weryfikacje witryny](https://foura.ai/docs/api/site-checks), aby poznać wszystkie pola i pełną listę systemów. |
| `error` | string | Komunikat o błędzie w przypadku niepowodzenia żądania |

---

## Żądanie proxy

`POST /api/proxy/`

Kieruje Twoje żądanie przez rotacyjne proxy z automatycznym ponawianiem w przypadku błędu. Opcjonalnie zawęża wybór do zestawu krajów wyjściowych widocznych dla celu.

### Ciało żądania

| Parametr | Typ | Wymagany | Domyślnie | Opis |
|-----------|------|----------|---------|-------------|
| `request` | object | Tak | - | Pojedynczy request body (te same pola co w Single Request powyżej) |
| `timeout_ms` | number | Nie | 45000 | Całkowity timeout dla wszystkich prób w ms (maksymalnie: 120000) |
| `maxTries` | number | Nie | 5 | FourA przestaje uruchamiać nowe próby, gdy tyle z nich zakończy się niepowodzeniem (maksymalnie: 90). Próby działają równolegle, więc może zakończyć się ich nieco więcej niż ta liczba. |
| `ignoreProxies` | string[] | Nie | - | Identyfikatory proxy do wykluczenia z rotacji (użyj identyfikatorów zwróconych przez poprzednie odpowiedzi) |
| `exitCountries` | string[] | Nie | - | Ścisła lista dozwolonych dwuliterowych kodów krajów widocznych dla celu (np. `["CZ", "GB"]`). Wartości są przycinane, zamieniane na wielkie litery i deduplikowane. Węzły wyjściowe z puli standardowej o nieznanym kraju są wykluczane, a pula standardowa nigdy nie przełącza się na niewskazany kraj. Węzeł wyjściowy premium również pochodzi z jednego z wymienionych krajów. |
| `exitClass` | string | Nie | - | `standard` lub `premium`. `premium` pozwala na eskalację żądania do węzła premium, gdy standardowa pula ma trudności z chronionym celem. Wymaga planu obejmującego węzły wyjściowe premium. |
| `exitState` | string | Nie | - | Region, z którego wychodzi połączenie. Wymaga `exitClass: premium` i dokładnie jednego kraju w `exitCountries`. Zobacz [Exit location](#exit-location). |
| `exitCity` | string | Nie | - | Miasto, z którego wychodzi połączenie. Wymaga `exitClass: premium` i dokładnie jednego kraju w `exitCountries`. |
| `exitAsn` | string | Nie | - | Sieć, z której wychodzi połączenie, według numeru AS, na przykład `8866`. Wymaga `exitClass: premium` i dokładnie jednego kraju w `exitCountries`. |
| `exitOs` | string | Nie | - | `windows`, `android`, `ios` lub `mac`: typ urządzenia, do którego należy adres. Wymaga `exitClass: premium`. |
| `exitLifetimeMin` | integer | Nie | - | Minuty, przez które węzeł wyjściowy zachowuje swój adres, od `3` do `1440`. Wymaga `exitClass: premium`. |

### Zakres exitCountries

Wybór korzysta z najnowszych dostępnych metadanych o kraju widocznym dla celu, zwykle odświeżanych w ciągu około dziesięciu minut. Nie jest to geolokalizacja na żywo podczas wykonywania żądania. Nie należy wnioskować kraju obsługującego na podstawie adresu hosta proxy.

Jeśli bieżąca pula nie zawiera dopasowania dla żądanych krajów, a żądanie nie wskazywało `exitClass: premium`, odpowiedź 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
}
```

Zachowaj żądany zakres i ponów próbę później. Zmień go lub rozszerz tylko wtedy, gdy wymagania dotyczące kraju w Twoim przepływie pracy wyraźnie się zmienią.

### Przykład

```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": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'
```

Odpowiedź:

```json
{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
```

| Pole | Typ | Opis |
|-------|------|-------------|
| `proxy` | string | Zakodowany identyfikator użytego proxy. Użyj go ponownie w żądaniu Single lub Browser, przekazując go jako pole `proxy`, albo pomiń go w kolejnym żądaniu Proxy za pomocą `ignoreProxies`. |
| `exitCountry` | string | Dwuliterowy kod kraju proxy widoczny dla celu, które obsłużyło request. Występuje tylko wtedy, gdy w żądaniu ustawiono `exitCountries`, niezależnie od klasy węzła wyjściowego. Zawsze weryfikuj, czy jest to jeden z żądanych kodów, zanim uznasz odpowiedź za zaufaną. |
| `exitClass` | string | Klasa węzła wyjściowego, która obsłużyła ten request; pole obecne przy udanej odpowiedzi, gdy w żądaniu wskazano klasę. Wartość `premium` oznacza, że treść zwrócił węzeł premium; `standard` oznacza standardową pulę. Nieudane wywołanie niczego nie obsłużyło, więc nie zawiera `exitClass`; sprawdź jego pole `attemptReport`, aby dowiedzieć się, co napotkały próby. |
| `total` | number | Całkowity czas zegarowy w sekundach (float). Obejmuje wybór proxy, ponowienia oraz udaną próbę. `total_time` dotyczy tylko wewnętrznego requestu; `total` jest zawsze >= `total_time`. |
| `profile` | string | Profil przeglądarki wybrany przez rotację, obecny **tylko** wtedy, gdy nie był to profil żądany przez Ciebie. Brak pola oznacza, że request wyszedł dokładnie w podanej postaci. Przekaż ten id z powrotem jako `profile` w kolejnych wywołaniach, aby zachować działającą przeglądarkę. |
| `error` | string | Komunikat błędu, jeśli request się nie powiódł. Przy braku dopasowania zakresu (scope miss), `code` ma wartość `no_eligible_proxy`, a `details.exitCountries` zwraca znormalizowany scope. |
| `attemptReport` | object | Obecne przy **każdym** nieudanym wywołaniu Proxy. Zlicza przeszkody napotkane podczas prób, dzięki czemu zablokowana pula, martwa pula oraz reguła `validate`, która nigdy nie została dopasowana, nie wyglądają jak ten sam błąd. Zobacz poniżej. |
| `request` | object | Obecne przy nieudanym wywołaniu Proxy: request wykonany przez FourA, z uzupełnionymi wartościami domyślnymi oraz Twoimi `ignoreProxies` w przesłanej postaci. |

Wszystkie pola odpowiedzi Single Request są również dołączone, w tym `defense`: próba proxy, która napotkała weryfikację bota, raportuje to w taki sam sposób jak Single.

### Dlaczego wywołanie Proxy zakończyło się niepowodzeniem

`Download maxTry limit reached` ma taką samą postać niezależnie od przebiegu prób, dlatego każda nieudana odpowiedź Proxy zawiera `attemptReport` obok błędu:

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

| Pole | Typ | Opis |
|-------|------|-------------|
| `total` | integer | Liczba podjętych prób |
| `noResponse` | integer | Węzeł wyjściowy nie odpowiedział, więc połączenie ze stroną nie zostało nawiązane |
| `defense` | integer | Strona odpowiedziała i w tej odpowiedzi wykryto weryfikację botów |
| `contentRejected` | integer | HTTP 200, brak weryfikacji botów, odrzucone wyłącznie przez Twój `validate.data` |
| `statusRejected` | integer | Strona odpowiedziała, brak weryfikacji botów, odrzucone przez Twój `validate.status` |
| `other` | integer | Uzyskano odpowiedź i żaden z powyższych przypadków nie miał miejsca |
| `vendors` | string[] | Dostawcy weryfikacji botów wykryci w dowolnym momencie zadania |
| `profilesTried` | string[] | Profile przeglądarek wysłane przez zadanie, w kolejności pierwszego użycia. `default` oznacza, że request został wysłany bez zmian. |
| `summary` | string | Jedno zdanie zbudowane na podstawie liczników, bezpieczne do logowania |

Ciąg `error` pozostaje niezmieniony, więc klient dopasowujący go nadal działa poprawnie. Co zrobić z poszczególnymi licznikami: [Dlaczego proxy request wyczerpał limit prób](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### exitClass

Niektóre cele odrzucają węzły wyjściowe ze standardowej puli bez względu na liczbę prób. `exitClass: premium` informuje Proxy, że może eskalować taki request do **węzła wyjściowego premium** poza standardową pulą, zamiast wyłącznie rotować w jej obrębie.

```json
{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}
```

Warto wiedzieć o trzech kwestiach przed wysłaniem żądania.

**To limit, a nie instrukcja.** Pula standardowa nadal konkuruje o odpowiedź i zwykle wygrywa. Węzeł wyjściowy premium dołącza dopiero wtedy, gdy pula wyczerpie krótki limit czasu na żądanie lub cel wyraźnie je odrzuci. Żądanie obsłużone przez pulę standardową, zanim podjęto próbę z węzłem premium, jest zwykłym sukcesem i nie zużywa transferu premium. Gdy próba z węzłem premium zostanie podjęta, jego transfer jest naliczany zgodnie z poniższym opisem.

**Węzeł wyjściowy premium pozostaje w ramach `exitCountries`.** W przypadku listy krajów węzeł wyjściowy premium pochodzi z jednego z nich, a `exitCountry` w odpowiedzi wskazuje go tak samo, jak dla puli standardowej.

**Odpowiedź informuje, co faktycznie obsłużyło żądanie.** Po wskazaniu klasy odpowiedź zwraca `exitClass`:

```json
{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}
```

`premium` oznacza, że treść została zwrócona przez węzeł wyjściowy premium. `standard` oznacza, że odpowiedź pochodzi ze standardowej puli, co ma miejsce także wtedy, gdy nie udało się uzyskać węzła premium oraz gdy limit transferu premium w ramach Twojego planu (wraz z dokupionym pakietem) został wyczerpany w danym okresie rozliczeniowym. Żadna z tych sytuacji nie jest błędem, a zużycie transferu premium możesz weryfikować na poziomie pojedynczego requestu zamiast sumy miesięcznej. Ta sama wartość jest przesyłana w nagłówku odpowiedzi `X-FourA-Exit-Class` (zobacz [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**Transfer premium jest mierzony na poziomie sieci.** Próba z użyciem węzła premium zlicza dane wysłane i odebrane w sieci, z uwzględnieniem kompresji i szyfrowania, niezależnie od tego, czy strona została zwrócona. Próba, która wciąż trwała, gdy inny węzeł wyjściowy zwrócił odpowiedź, jest natychmiast przerywana, a przesłany do tego momentu ruch również jest wliczany. Transfer premium wlicza się do Twojego limitu premium oraz do całkowitego transferu: te same bajty są raportowane dwukrotnie, nigdy sumowane. Gdy strona została dostarczona przez węzeł premium, jego ruch stanowi całkowity ruch danego requestu, więc strona nie jest liczona ponownie jako ruch standardowy. Strona [Usage & Limits](https://foura.ai/docs/dashboard/quota) pokazuje łączny transfer, jego część premium oraz limit premium, według którego następuje rozliczenie.

Pominięcie tego pola oraz przesłanie `standard` kierują request do standardowej puli: tylko `premium` zezwala na węzeł wyjściowy premium. Udany request określający klasę otrzymuje w odpowiedzi `exitClass`, a request pomijający to pole go nie ma.

**Wyczerpanie limitu nie jest błędem.** Request ze wskazaniem `premium` po wyczerpaniu limitu nadal działa: standardowa pula go obsługuje, a odpowiedź zwraca `standard`. Jedynym wyjątkiem jest request ze wskazaniem parametru [exit location](#exit-location): standardowa pula nie może go obsłużyć, więc zostaje odrzucony.

`exitClass: premium` wymaga planu obejmującego węzły wyjściowe premium. W planie bez tej opcji request nigdy nie zużywa węzła premium: jest odrzucany ze statusem 403 i kodem `X-FourA-Limit: plan_limit_premium` (zobacz [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits)), zanim zostaną wykonane jakiekolwiek operacje.


### Lokalizacja węzła wyjściowego

Węzeł wyjściowy premium może pochodzić z określonego miejsca w danym kraju i zachować swój adres tak długo, jak to potrzebne:

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

Odpowiedź zawiera nazwę węzła wyjściowego oraz kraj, z którego nastąpiło wyjście:

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

Ten identyfikator `proxy` zachowuje wszystko. Przekaż go do Single lub Browser, a żądanie wyjdzie z tego samego miejsca, bez żadnego innego pola obok. Zobacz [Przypinanie węzła wyjściowego](#pinning-an-exit).

Zasady:

- Użycie dowolnego z pól `exitState`, `exitCity`, `exitAsn`, `exitOs` lub `exitLifetimeMin` kieruje żądanie wyłącznie przez węzły wyjściowe premium. Standardowa pula nie podejmuje żadnej próby, ponieważ nie może ich obsłużyć.
- Wymagają one pola `exitClass: premium`. Bez niego żądanie zostanie odrzucone z kodem 400 wskazującym brakujące pole.
- Pola `exitState`, `exitCity` i `exitAsn` istnieją w ramach jednego kraju, dlatego wymagają dokładnie jednego kraju w `exitCountries`. Pola `exitOs` i `exitLifetimeMin` działają z wieloma: węzeł wyjściowy wybiera jeden z nich, a nagłówek `exitCountry` w odpowiedzi wskazuje, który wybrano.
- Pola `exitState`, `exitCity`, `exitAsn` i `exitOs` wymagają planu z obsługą geotargetowania oraz węzłów wyjściowych premium.
- W przypadku wyczerpania transferu premium żądanie jest odrzucane z kodem 403 i błędem `X-FourA-Limit: plan_limit_premium`, ponieważ pula standardowa nie może go zrealizować.
- Jeśli żaden węzeł wyjściowy premium nie odpowiada dla danej lokalizacji, odpowiedź ma postać koperty błędu, takiej jak w sekcji [Zakres exitCountries](#exitcountries-scoping), z kodem błędu `No premium exit answered for this request` i polem `code: no_eligible_proxy`. Pole `details.exitCountries` pojawia się, gdy przesłano listę krajów.

Wartości są takie same, jakie [port proxy](https://foura.ai/docs/api/proxy-port) przyjmuje dla `state`, `city`, `asn` i `os`.

### Rotacja profili przeglądarki

Proxy rotuje węzły wyjściowe. Gdy strona odrzuca przeglądarkę przedstawioną przez FourA, a nie sam węzeł wyjściowy, Proxy przełącza się również na inną rodzinę przeglądarek z katalogu. Nie dodaje to kolejnej próby: rotacja zmienia parametry wysyłane w ramach ponowienia, a nie fakt jego wykonania.

Proxy zapamiętuje także przez pewien czas rodzinę przeglądarek ostatnio zaakceptowaną przez witrynę, dzięki czemu kolejne wywołanie do tej samej witryny może rozpocząć się od tej rodziny zamiast domyślnej. Odpowiedź wskazuje ją w `profile`, tak jak w przypadku każdej rodziny wybranej przez mechanizm rotacji.

Jawne wartości `profile`, `browser`, `os` lub `version` w wewnętrznym obiekcie `request` nigdy nie są nadpisywane, podobnie jak żądanie zawierające własny nagłówek `User-Agent` lub `Cookie`, ponieważ autoryzacja clearance jest powiązana z sygnaturą, która ją uzyskała.

---

## Żądanie Browser

`POST /api/browser/`

Otwiera podany URL w instancji przeglądarki Chrome. Strona się ładuje, wykonywany jest kod JavaScript, a w rezultacie otrzymujesz w pełni wyrenderowany kod HTML wraz z plikami cookie.

### Treść żądania

| Parametr | Typ | Wymagany | Domyślnie | Opis |
|-----------|------|----------|---------|-------------|
| `url` | string | Tak | - | Docelowy URL |
| `headers` | object | Nie | - | Niestandardowe nagłówki jako pary klucz-wartość |
| `cookies` | array | Nie | - | Pliki cookie do ustawienia: `[{name, value, domain?}]` |
| `userAgent` | string | Nie | - | Niestandardowy ciąg User-Agent |
| `unblocker` | boolean | Nie | `true` | Wykonuje weryfikację wymaganą przez stronę przed jej załadowaniem (strona challenge lub podobna blokada). Domyślnie włączone. Ustaw `false`, aby renderować dokładnie to, co zwraca strona, w tym stronę challenge. |
| `proxy` | string | Nie | - | Identyfikator proxy z wcześniejszej odpowiedzi, aby przypiąć ten sam węzeł wyjściowy. Przekaż nieprzezroczysty ciąg znaków bez zmian. Bezpośredni adres proxy jest odrzucany z błędem `400 Invalid proxy format`. |
| `timeout_ms` | number | Nie | 30000 | Limit czasu ładowania strony w ms (maks.: 120000) |
| `checkStatus` | number | Nie | - | Oczekiwany status HTTP (żądanie kończy się błędem, jeśli jest inny) |
| `checkText` | string | Nie | - | Tekst, który musi pojawić się na wyrenderowanej stronie |
| `lean` | boolean | Nie | `false` | Pomija obrazy, czcionki, multimedia oraz żądania do znanych usług reklamowych, analitycznych, zgód i społecznościowych. Sama strona, jej skrypty, style oraz elementy wymagane przez krok weryfikacji nadal się ładują. Użyj tego, aby zmniejszyć transfer zużywany przez stronę, na przykład przez przypięty węzeł premium. |

### Dopasowywanie zegara przeglądarki do węzła wyjściowego

Strona może odczytać strefę czasową przeglądarki i porównać ją z krajem adresu IP, który widzi. Rozbieżność to jeden z najprostszych sygnałów dla systemów wykrywania botów, a jej eliminacja nic nie kosztuje.

Nie musisz nic robić. FourA odczytuje kraj z identyfikatora `proxy`, a przeglądarka zgłasza odpowiednią dla niego strefę czasową.

- Chodzi o kraj **węzła wyjściowego**, czyli kraj widziany przez cel, a nie miejsce hostowania proxy. Te dwie lokalizacje różnią się na tyle często, że ma to znaczenie.
- Jeśli FourA nie zna kraju węzła wyjściowego, pozostawia zegar przeglądarki bez zmian, zamiast zgadywać. Węzeł premium ma znany kraj, jeśli został wskazany za pomocą `exitCountries` w [Proxy Request](#exit-location).
- Tylko zegar dostosowuje się do kraju. Nagłówek `Accept-Language` oraz treść serwowana przez witrynę pozostają nienaruszone, więc strona nie zmieni niespodziewanie języka.

### Parametr `userAgent`

Wyślij `userAgent`, a strona, jej procesy worker i cel zobaczą dokładnie ten ciąg. FourA generuje z niego także dopasowane client hints (`sec-ch-ua`, `sec-ch-ua-platform`, `navigator.platform` oraz wartości o wysokiej entropii, których detektor wymaga bezpośrednio), dzięki czemu żądanie nie wskazuje na inną przeglądarkę w nagłówku, a inną w JavaScript.

Wartość `userAgent` w odpowiedzi to ta, która została faktycznie użyta. Ma to znaczenie przy ponownym użyciu clearance: plik cookie `cf_clearance` jest powiązany z węzłem wyjściowym oraz ciągiem User-Agent, który go uzyskał, dlatego należy odesłać ciąg zwrócony w odpowiedzi, a nie ten, którego użycie zakładano. Zobacz [Site checks](https://foura.ai/docs/api/site-checks).

Wyślij ciąg inny niż Chromium (na przykład User-Agent przeglądarki Firefox), a zostanie on przesłany w niezmienionej formie, bez dołączonej listy marek Chromium.

### Przykład

```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/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Response:

```json
{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
```

| Pole | Typ | Opis |
|-------|------|-------------|
| `status` | number | Kod statusu HTTP z serwera docelowego |
| `headers` | object | Nagłówki odpowiedzi |
| `body` | string lub object | W pełni wyrenderowana zawartość strony. Ciąg znaków HTML, gdy content-type to HTML; obiekt, gdy strona zwróciła JSON i został on automatycznie sparsowany. |
| `cookies` | array | Pełne obiekty cookie ze strony. Każde cookie zawiera `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite` oraz inne właściwości cookie. |
| `userAgent` | string | Użyty User-Agent przeglądarki |
| `defenseSolved` | boolean | `true`, jeśli podczas tego wywołania napotkano i rzeczywiście ominięto ochronę przed botami; w przeciwnym razie `false`. Decyduje o tym, czy wywołanie kosztuje 5 czy 10 kredytów. |
| `defenses` | object | `present` wymienia każdego dostawcę zabezpieczeń wykrytego podczas ładowania strony, `cleared` wymienia tych, których autoryzację zachowała ostateczna strona. Dostawca może pojawić się w `present` i nigdy w `cleared`. Zobacz [Weryfikacje stron](https://foura.ai/docs/api/site-checks). |
| `proxy` | string | Zakodowany identyfikator proxy, przez który przeszło żądanie (tylko wtedy, gdy w żądaniu podano `proxy`). Użyj go ponownie w kolejnych wywołaniach, aby zachować ten sam węzeł wyjściowy. |
| `error` | string | Komunikat o błędzie, jeśli żądanie się nie powiodło |

---

## Przypinanie węzła wyjściowego

Wartość `proxy` w żądaniu Single lub Browser przypina węzeł wyjściowy użyty przez poprzednie wywołanie. Przekaż nieprzezroczysty identyfikator dokładnie w takiej postaci, w jakiej został zwrócony, nigdy jako adres proxy. Identyfikator z żądania Proxy, który określał kraj, lokalizację lub czas życia, zachowuje te parametry, więc przypięte żądanie nie wymaga żadnego innego pola.

Odrzucane są trzy wartości, wszystkie z kodem 400:

| Błąd | Znaczenie |
|-------|---------|
| `Invalid proxy format` | Wartość nie jest identyfikatorem wystawionym przez FourA. Bezpośredni adres proxy skutkuje tym błędem. |
| `Proxy not found` | Identyfikator został zdekodowany, ale nie wskazuje już na aktywny węzeł wyjściowy. Pobierz nowy identyfikator z nowego wywołania. |
| `Managed exit: this proxy id cannot be pinned to a request` | Węzeł wyjściowy istnieje, ale nie jest węzłem, który FourA utrzyma dla wskazanego żądania. Identyfikator węzła premium trafi tutaj, gdy w Twoim planie skończy się transfer premium. Użyj ponownie sesji, w której został zwrócony, lub wykonaj wywołanie przez `POST /api/proxy/` i zaakceptuj dowolny wybrany przez nie węzeł wyjściowy. |

Przypięty węzeł wyjściowy premium jest rozliczany jako ruch premium. Odpowiedź zawiera `X-FourA-Exit-Class: premium`, dzięki czemu można monitorować go dla każdego żądania, a ruch obsłużony przez węzeł wlicza się do limitu transferu premium na stronie [Użycie i limity](https://foura.ai/docs/dashboard/quota), jak również do całkowitej przepustowości, niezależnie od tego, czy witryna zwróciła żądaną stronę. Przypinanie wymaga dostępności węzłów premium w Twoim planie oraz pozostałego limitu; w przeciwnym razie identyfikator zostanie odrzucony z powyższym błędem 400 dla zarządzanego węzła.

## Kody statusu HTTP

| Kod | Znaczenie |
|------|---------|
| 200 | Żądanie zakończone (sprawdź wewnętrzne `status` dla odpowiedzi docelowej) |
| 400 | Nieprawidłowa treść żądania, parametry, docelowy IP w zakresie prywatnym/zarezerwowanym, cel na własnym hoście API FourA, adres URL z niezakodowaną spacją (Single, Proxy, Auto) lub identyfikator proxy, którego nie można przypiąć. W Single, Proxy i Browser pole, które nie przeszło walidacji, jest nazwane: `Invalid request: <field>: <reason>`, maksymalnie do pięciu pól. Brak opłaty. Auto odpowiada na ten sam błąd kodem HTTP 200 i `status: 400` w treści. |
| 401 | Brakujący lub nieprawidłowy klucz API |
| 403 | Endpoint lub parametr nie jest dostępny w Twoim planie. `X-FourA-Limit` wskazuje: `plan_limit_feature` lub `plan_limit_premium`. |
| 404 | `Not Found`: brak endpointu pod tą ścieżką. |
| 413 | Treść żądania JSON przekracza 100 KB. Odpowiedź nie jest formatem JSON i nie zawiera nagłówka `X-FourA-Request-Id`. |
| 429 | Limit planu (ustawiony nagłówek `X-FourA-Limit`) lub współdzielony limit platformy na minutę (brak nagłówka) |
| 500 | Wewnętrzny błąd serwera |
| 502 | `Upstream unavailable`: FourA nie mogło połączyć się ze swoim silnikiem. `Malformed JSON from backend`: silnik odpowiedział, ale FourA nie mogło odczytać odpowiedzi. Ponów próbę. |
| 503 | Usługa tymczasowo wyłączona lub przeciążona, `API key check temporarily unavailable`, gdy FourA nie mogło chwilowo potwierdzić Twojego klucza (ponów próbę po upływie `Retry-After`), lub `Backend service unavailable` podczas restartu silnika. W trybie Browser strona czeka do 10 sekund na wolną przeglądarkę, gdy wszystkie są zajęte, i otrzymuje `Backend service unavailable`, jeśli żadna nie zwolni się w tym czasie. |
| 504 | `Upstream timeout`. Silnik nie ukończył działania w wyznaczonym limicie czasu dla tego żądania. Zwiększ `timeout_ms` lub ponów próbę. |

## Kolejne kroki

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Kiedy pozwolić FourA na automatyczny wybór ścieżki
- [Wybór odpowiedniego endpointu](https://foura.ai/docs/guides/choosing-task-type): Kiedy ręcznie wybrać Single, Proxy lub Browser
- [Uwierzytelnianie](https://foura.ai/docs/getting-started/authentication): Zarządzaj swoimi kluczami API
- [Obsługa błędów](https://foura.ai/docs/api/errors): Prawidłowo obsługuj błędy
- [Weryfikacje stron](https://foura.ai/docs/api/site-checks): Odczytaj pole `defense` i powtórz weryfikację
- [Dlaczego żądanie Proxy wyczerpało próby](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Odczytaj `attemptReport` i podejmij działanie
- [Limity zapytań](https://foura.ai/docs/api/rate-limits): Poznaj rate limity
- [Szybki start](https://foura.ai/docs/getting-started/quick-start): Twoje pierwsze żądanie w 30 sekund
