# Ошибки API

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

Как обрабатывать ошибки API FourA.

## Формат ответа с ошибкой

API возвращает плоские объекты JSON для всех ошибок. Вложенный объект `error` отсутствует. Если у сбоя есть машиночитаемый код, он находится в поле верхнего уровня: `reason` при превышении лимита тарифа, `code` при вызове proxy без подходящего выхода.

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

Некоторые ошибки содержат дополнительные поля, такие как `status`, `service`, `retryAfter`, `current` или `limits` на верхнем уровне:

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

## Отслеживание request

Каждый API response (успешный или с ошибкой) содержит header `X-FourA-Request-Id` с UUID для этого вызова, за исключением случаев, когда FourA вовсе не может прочитать body (некорректный JSON или body более 100 KB): такие запросы отклоняются до назначения ID. Логируйте его на своей стороне. Если вам потребуется уточнить у поддержки статус конкретного request, этот ID позволит нам его найти.

```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
# ...
```

## Типы ошибок

### 400: Некорректный запрос

Тело request не содержит обязательных полей, содержит недопустимые значения или указывает цель, которую API отказывается запрашивать.

Тело, которое не является объектом или массивом JSON, считается некорректным JSON и возвращает `Invalid JSON in request body`, как показано ниже.

В Single, Proxy Finder и Browser отсутствующее поле, поле с неверным типом или значением вне диапазона указывается в сообщении как `<field>: <reason>`. Вложенные поля объединяются точками (`validate.status.accept`). Указывается до пяти проблем через разделитель `; `, а любые последующие завершают сообщение как `and <n> more`:

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

Это `client_error`, и плата за него не взимается. Auto вместо этого сообщает о поле, которое не может принять, внутри HTTP 200, как описано ниже в разделе Reading Failures from `/api/auto/`.

Этот же статус 400 применяется для защиты от SSRF. Если ваш `url` резолвится в приватный, loopback или иной зарезервированный диапазон IP (RFC 5735, RFC 6598, зарезервированные блоки IPv6), request отклоняется до выхода из сети 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>` представляет собой адрес или имя хоста и адрес, в который оно разрешилось. URL, который не удается распарсить или который не является `http://` либо `https://`, возвращает ту же ошибку 400.

Целевой адрес на собственном API-хосте FourA (`eu.api.foura.ai` или `api.foura.ai`) также возвращает 400 в режимах Single, Proxy Finder, Browser и Auto, еще до выполнения запроса или списания средств. Обычно это означает, что ссылка со страницы была разрешена относительно URL API, а не URL самой страницы:

```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>` - это целевой URL в точности в том виде, в котором вы его отправили. Страница [Inspect](https://foura.ai/docs/api/inspect) является единственным исключением: FourA все равно выполняет запрос к `https://eu.api.foura.ai/inspect` для вас.

URL, содержащий пробел или управляющий символ, также возвращает 400 на Single, Proxy Finder и Auto до отправки запроса и списания средств. Ссылка, скопированная со страницы как есть, часто содержит такие символы (`javascript: void(0)`, ссылка для шеринга с пробелами в тексте). Кодируйте их, заменяя пробел на `%20`. Browser выполняет запрос к такому URL так же, как Chrome:

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

Имя хоста, которое не удается разрешить, не отклоняется сразу. Вызов возвращает HTTP 200 с `status: 0` и причиной (`could not resolve <host>: <reason>`), и плата за него не взимается. Целевой ресурс, к которому обращается FourA, но не получает HTTP-ответа (исчерпан лимит перенаправлений, таймаут соединения или чтения, сброс соединения), также возвращает HTTP 200 с `error` и `total_time` без `status`: см. [Request Outcomes](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like).

На тарифе Single тело ответа размером более 128 МБ после декодирования прерывается. Вызов возвращает HTTP 200 с `"error": "Response body exceeds the 128 MB limit"` и не тарифицируется.

Некорректный JSON в теле запроса отклоняется аналогичным образом, до чтения каких-либо полей:

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

У полей `proxy` и `ignoreProxies` есть собственные ошибки 400. Оба принимают непрозрачные идентификаторы proxy ID из предыдущих ответов, поэтому любые другие значения декодировать не удастся:

| Сообщение | Причина |
|---------|---------------|
| `Invalid proxy format` | Значение `proxy` не является proxy ID, выданным FourA. Прямой адрес proxy приводит к этой ошибке. |
| `Invalid ignoreProxies format` | Одно из значений в `ignoreProxies` не является proxy ID. |
| `Proxy not found` | Идентификатор успешно декодирован, но больше не указывает на активный выходной узел. Выберите новый узел. |
| `Managed exit: this proxy id cannot be pinned to a request` | Выходной узел существует, но FourA не удерживает его открытым для именованного запроса. ID премиум-узла вызывает эту ошибку, если в вашем тарифе закончился премиум-трафик. Используйте сессию, в которой он был получен, или выполните вызов через `POST /api/proxy/` и используйте назначенный узел. |

**Решение:** проверьте, что запрос содержит все обязательные поля, URL использует `http://` или `https://` с пробелами в виде `%20`, хост разрешается в публичный адрес, а любое значение `proxy` представляет собой ID, скопированный точно из предыдущего ответа.

Это результаты категории `client_error`: запрос не покидал FourA, поэтому ресурсы вашего тарифа списаны не были.

### 401: Не авторизован

Ваш API key отсутствует или недействителен.

Отсутствует ключ:

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

Недопустимый ключ:

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

**Решение:** убедитесь, что заголовок `X-API-Key` содержит действительный ключ. При необходимости сгенерируйте новый ключ в [Dashboard](https://foura.ai/dashboard).

Ошибка 401 всегда означает, что FourA проверил ваш ключ и отклонил его. Если FourA временно не может проверить ключ, возвращается 503 `API key check temporarily unavailable` (см. ниже), но не 401.

### 403: Не входит в ваш тарифный план

Запрос обратился к endpoint или параметру, который не включен в ваш тарифный план. В ответе устанавливается `X-FourA-Limit`, и этот же код передается в теле ответа в поле `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` возвращает `plan_limit_feature` для endpoint, не входящего в тариф, или для `exitCountries` и полей exit location на тарифе без геотаргетинга, а также `plan_limit_premium` для `exitClass: premium` на тарифе без премиум-выходов, либо для [exit location](https://foura.ai/docs/api/endpoints#exit-location) при исчерпании премиум-трафика. Строка `error` указывает конкретный endpoint или параметр.

Код 403 от FourA никогда не связан с целевым сайтом: обращения к нему не было. Ошибка 403, возвращенная целевым сайтом, приходит как HTTP 200 с `status: 403` в теле ответа.

**Решение:** удалите параметр, вызовите endpoint, входящий в тариф, или обновите тариф. Заголовок `Retry-After` не задается, так как ожидание не изменит результат. Средства не списаны: статус выполнения `rate_limit`, а тарифицируется только `success`.

### 413: Слишком большой размер полезной нагрузки

Тело запроса JSON превышает допустимый для FourA размер (100 КБ). Ответ возвращается не в формате JSON и не содержит `X-FourA-Request-Id`, так как тело отклоняется до его прочтения.

**Решение:** отправьте `data` меньшего размера. Средства не списаны.

### 429: Превышен лимит запросов

Код 429 возвращают две разные проверки, и они содержат разные поля.

**Собственные лимиты вашего тарифа.** В ответе передается заголовок `X-FourA-Limit` с указанием лимита, отклонившего вызов, а в теле ответа тот же код дублируется в поле `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` принимает одно из значений: `plan_limit_concurrency`, `plan_limit_rate`, `plan_limit_browser_daily`, `plan_limit_credits` или `plan_limit_bandwidth`. Если ожидание имеет смысл, время ожидания указывается в `retry_after_seconds` и в header `Retry-After`, но никогда в `retryAfter`. `plan_limit_browser_daily` не содержит ни того, ни другого, так как лимит восстанавливается в полночь по UTC, а не через секунды. Средства не списывались: результат `rate_limit`, а тарифицируется только `success`.

**Общий лимит платформы.** Заголовок `X-FourA-Limit` отсутствует, а время ожидания указано в `retryAfter`:

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

`current` и `limits` описывают состояние сервиса для всего трафика, а не для вашего аккаунта. Отказ здесь означает, что FourA перегружен.

**Решение:** Подождите время, указанное в `Retry-After`, `retry_after_seconds` или `retryAfter` из ответа. При ограничении параллелизма или rate limit ограничьте число открытых запросов вместо повторной отправки отклоненной пачки. При исчерпании дневного лимита или лимита расчетного периода остановите выполнение. См. [Rate Limits](https://foura.ai/docs/api/rate-limits) с описанием всех полей и [Параллельное выполнение запросов](https://foura.ai/docs/how-to/run-requests-in-parallel) для знакомства с шаблоном.

### 500: Ошибка сервера

Что-то пошло не так на нашей стороне.

**Решение:** Повторите запрос через небольшую паузу. Если ошибка повторяется, проверьте [страницу статуса](https://updates.foura.ai/status) или обратитесь в поддержку, указав `X-FourA-Request-Id` из неудавшегося ответа.

### 502: Вышестоящий сервис недоступен

FourA не смог получить ответ от собственного движка (`Upstream unavailable`: сбой соединения) или получил ответ, который не удалось прочитать (`Malformed JSON from backend`).

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

**Решение:** Повторите запрос с небольшой задержкой (backoff). Ошибка произошла на нашей стороне, поэтому она бесплатна: результат `service_error`, а списывается только `success`.

### 504: Таймаут вышестоящего сервиса

Движок не уложился в лимит времени, выделенный на этот request.

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

Ошибка 504 связана с длительностью выполнения задачи, а не с вашим ключом, параметрами или proxy. Обычные причины: медленные целевые ресурсы, решение проверок на холодную и тяжелые страницы.

**Решение:** увеличьте `timeout_ms` в request (Single принимает до 120000, Browser до 120000, Auto до 180000) или повторите попытку. FourA ожидает указанный вами лимит плюс небольшой запас, поэтому увеличение времени действительно дает дополнительное время на выполнение.

### 503: Сервис отключен или перегружен

Ошибка 503 означает, что сервис временно недоступен из-за технического обслуживания, либо исчерпан лимит параллельных запросов платформы. Оба варианта содержат одинаковые ключи: `error`, `status`, `service`, `retryAfter`, `current` и `limits`. Различайте их по значению строки `error`, а не по составу полей.

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

`Service disabled` означает техобслуживание, а `current` возвращает `0` для обоих счетчиков, так как request был отклонен до проведения измерений. `Service at capacity` представляет собой формат concurrency, и здесь `current` содержит реальную загрузку платформы. Структура описана в разделе [Rate Limits](https://foura.ai/docs/api/rate-limits).

**Решение:** Подождите `retryAfter` секунд, затем повторите попытку. На странице статуса указаны активные периоды обслуживания.

Третий вариант ответа 503 не содержит `retryAfter`. Это означает, что движок, обслуживающий ваш endpoint, не смог принять вызов: он перезапускался, произошел сбой на стороне FourA до выполнения вашего request или (для Browser) все браузеры оставались заняты в течение 10 секунд, отведенных на ожидание страницы. `backend_status` указывает собственный статус движка, а `detail` содержит начало его ответа:

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

Это `service_error`, и плата за него не списывается. Повторите запрос через пару секунд. Некорректный сам по себе request сюда не попадает: он получает 400 с указанием конкретного поля.

Четвертый 503 означает, что FourA временно не удалось проверить ваш API key, например, во время переключения базы данных. С вашим ключом все в порядке, и ничего не выполнялось. Ответ содержит `Retry-After: 5` и аналогичное ожидание в `retryAfter`:

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

Плата не списывается. Повторите запрос через `retryAfter` секунд. Ключ, подтвержденный FourA за последние 10 минут, продолжает работать в такой момент, поэтому данный ответ встречается редко.

## Чтение сбоев из `/api/auto/`

`POST /api/auto/` отвечает с HTTP 200 каждый раз, когда ladder запускался, даже если каждый шаг завершился сбоем. Фактический результат находится в body:

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

`status` содержит последний статус, возвращенный целевым ресурсом, либо 502, если ни одна попытка до него не дошла (504, если сначала истек лимит времени). Каждый неудачный ответ от выполненного каскада попыток также содержит `attemptReport` с подсчетом ошибок попыток, однострочный `summary`, который безопасно логировать, а `meta.attemptsByEngine` и `meta.browserRequests` указывают, что именно отправлял вызов. См. раздел [Why an Auto Call Failed](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed). Поле запроса, которое Auto не может принять (например, `timeout_ms` меньше 5000 или больше 180000), возвращается точно так же: HTTP 200 с `"status": 400` и причиной в `error`, до выполнения каких-либо попыток и совершенно бесплатно.

Поэтому не разветвляйте логику по транспортному статусу для Auto. Вместо этого читайте `status` и `error` из тела ответа. Настоящий non-200 статус от `/api/auto/` означает, что FourA отклонил вызов до запуска каскада или не смог его завершить: 400 (некорректный JSON, приватный или зарезервированный целевой ресурс, либо адрес самого API FourA), 401, 413, 502, 503 или 504. Одно ограничение тарифного плана проверяется сразу: `exitClass: premium` на тарифе без премиум-точек выхода возвращает 403 с `X-FourA-Limit: plan_limit_premium` до выполнения какой-либо работы. Все остальные лимиты, ваши или платформы, возвращаются внутри ответа 200 со своим статусом в теле.

Если сайт завершил ошибкой несколько вызовов Auto подряд с вашим API-ключом, Auto некоторое время будет сразу отвечать на следующие вызовы к нему для этого ключа без попыток отправки: `"error": "target temporarily unservable, retry later"`, `"status": 503` и `retryAfter` в секундах. Это бесплатно; подождите `retryAfter` секунд.

Лимит тарифа, достигнутый одним из подвызовов, также возвращается как HTTP 200. Тело содержит сам отказ с его `reason`, а также `status` и `meta`, при этом ответ содержит тот же заголовок `X-FourA-Limit`, что и прямой отказ:

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

Какие лимиты останавливают всю цепочку, а какие лишь закрывают отдельный шаг, описано в разделе [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## Сбои на стороне цели внутри 200 OK

Не каждый сбой возвращается в виде статуса HTTP, отличного от 2xx. Если цель отвечает HTTP 200, но ответ FourA содержит `error` (например, ваши правила `validate` отклонили тело ответа) или тело представляет собой страницу проверки, распознанную FourA, итогом будет `application_error`. Когда цель возвращает статус, отличный от 200, который не принимается вашими правилами `validate`, итогом будет `application_fail`, а тело ответа передается без изменений.

Ни один из этих случаев не тарифицируется: тарифицируется только `success`. Вызов Browser, при котором все браузеры заняты, ожидает освобождения до 10 секунд. Если ни один не освободился, возвращается 503 `Backend service unavailable`, описанный выше. Browser также может вернуть HTTP 200 с `"error": "No available browser slot"`, если не удалось выделить браузер вовсе. Оба случая не тарифицируются. Повторите запрос через несколько секунд или держите меньше открытых вызовов Browser одновременно. Полная классификация приведена в справочнике [Outcomes](https://foura.ai/docs/api/outcomes).

Вызов Single через закрепленный вами `proxy` также может вернуть HTTP 200 с кодом `"error": "The exit gave the same answer for <n> different sites"` рядом с телом ответа. FourA зафиксировал, что этот узел отдавал ту же страницу несвязанным сайтам, то есть страница принадлежит самому узлу, а не запрошенному ресурсу. Это считается `application_error` и не тарифицируется. Возьмите новый узел из `POST /api/proxy/`, который пропускает такие узлы автоматически.

То же самое применимо, когда вместо сайта отвечает собственная сеть выходного узла. Вызов возвращает `"error": "The exit answered instead of the site (<name>)"` или `"error": "Corporate web gateway intercepted the request (<name>)"` (страница входа, фильтрации или редирект на нее), `"error": "The exit intercepted TLS and answered instead of the site (<name>)"`, когда узел ответил от имени самого сайта, или `"error": "Honeypot echo proxy (plaintext request dump)"`, когда узел вернул копию вашего собственного запроса. FourA проверяет эти ситуации независимо от ваших правил `validate`, включая загрузки `returnBuffer`. Ни один из этих случаев не тарифицируется. Получите новый узел аналогичным образом.

## Кодировка ответа

FourA автоматически декодирует тело ответа в UTF-8. Если цель отдает `windows-1251`, `gbk`, `shift_jis`, `iso-8859-*` или любую другую кодировку, указанную в заголовке `Content-Type` либо в теге HTML `<meta charset>`, вы получаете чистую строку UTF-8 в поле `data` (single, proxy) или `body` (browser).

Для бинарных данных (изображения, protobuf, аудиопотоки) укажите `returnBuffer: true` в запросе. В этом случае Single и Proxy возвращают `data` как объект с исходными байтами, `{"type": "Buffer", "data": [<byte values>]}`, без перекодирования набора символов.

## Стратегия повторных попыток

Практическая политика повторных попыток:

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

## Сбои прокси содержат отчет

Вызов `POST /api/proxy/`, исчерпавший все попытки, возвращается как HTTP 200 с оболочкой ошибки (error envelope), а не как код ошибки HTTP. Строка ошибки короткая и всегда имеет одинаковую структуру, поэтому рядом с ней передается объект `attemptReport` со счетчиками:

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

Логируйте `attemptReport.summary` вместе с ошибкой, и вы поймете, были ли выходные узлы заблокированы, недоступны или возвращали страницы, которые отклонили ваши собственные правила `validate`. Справочник по полям и действия для каждого счетчика: [Почему у proxy request закончились попытки](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

## Связанные разделы

- [Rate Limits](https://foura.ai/docs/api/rate-limits): лимиты тарифа, параллелизм и детали RPM
- [Параллельное выполнение запросов](https://foura.ai/docs/how-to/run-requests-in-parallel): соблюдение лимита параллелизма вашего тарифа
- [Результаты запросов](https://foura.ai/docs/api/outcomes): описание семи значений outcome
- [Частые проблемы](https://foura.ai/docs/troubleshooting/common-issues): симптомы, причины, решения
- [Проверки сайтов](https://foura.ai/docs/api/site-checks): когда в теле ответа страница с проверкой вместо ошибки
- [Почему у proxy request закончились попытки](https://foura.ai/docs/troubleshooting/proxy-attempt-report): чтение `attemptReport`
