Docs › Диагностика › Чести проблеми

Чести проблеми

Решения на най-често срещаните проблеми при използване на FourA API.

Празно или непълно съдържание

Симптом: API връща статус 200, но полето data е празно или липсва очакваното съдържание.

Причина: Целевата страница използва JavaScript за изобразяване на съдържание след първоначалното зареждане на страницата.

Решение: Преминете от единичния endpoint към браузърния endpoint. Използвайте checkText, за да потвърдите зареденото съдържание:

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Забележка: browser endpoint връща съдържание в полето body (а не data).

403 Forbidden или CAPTCHA страници

Симптом: API връща HTML, съдържащ CAPTCHA предизвикателство или страница за отказан достъп.

Причина: Целевият сайт е засякъл заявката като автоматизирана и я е блокирал.

Решение: Използвайте proxy endpoint за автоматична ротация на IP адреси:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

Ако проблемът продължава, увеличете maxTries, за да осигурите повече опити за ротация на proxy.

Timeout грешки

Симптом: Заявките са неуспешни с грешка за timeout.

Причина: Целевата страница се зарежда по-бавно от конфигурирания timeout.

Решение: Увеличете timeout_ms (по подразбиране е 15s за единична заявка, 30s за браузър, 45s за proxy):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

За заявки през браузър, също така проверете дали стойността ви за checkText действително се появява на страницата. Печатна грешка винаги ще доведе до timeout.

429 Твърде много заявки (Ограничение на RPM)

Симптом: API връща статус 429 със съобщение "rate limit exceeded".

Причина: Превишили сте ограничението си за заявки в минута (RPM). Това е различно от ограниченията за паралелност (вижте 503 по-долу).

Решение: Използвайте полето retryAfter от отговора, за да изчакате необходимото време преди нов опит:

import time
import requests

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

Проверете текущото си потребление в Dashboard, за да видите своите rate limits.

503 Service Unavailable

Симптом: API връща статус 503.

Причина: Това се случва в два случая:

  1. Достигнат лимит на паралелни заявки. Имате твърде много едновременни изпълнявани заявки. Това се различава от 429, който ограничава заявките в минута. При 503 не сте надвишили вашия RPM, но сте достигнали максималния брой заявки, които могат да се изпълняват едновременно.
  2. Услугата е временно недостъпна. Извършва се техническа поддръжка.

И двата случая включват поле retryAfter в response.

Решение: Изчакайте retryAfter секунди, след което опитайте отново:

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Ако редовно достигате лимитите за едновременност с код 503, намалете броя на паралелните заявки във вашия scraping pipeline или проверете лимита на вашия план в Dashboard.

504 Upstream Timeout

Симптом: API връща 504 с {"error": "Upstream timeout"}.

Причина: Работата не приключи в рамките на времевия бюджет, който сте декларирали за тази заявка. Бавна цел, бавно първоначално решаване на challenge или много голяма страница могат да причинят това. Проблемът не е във вашия ключ, вашите параметри или вашия proxy.

Решение: Осигурете повече време за извикването или опитайте отново. FourA изчаква вашето timeout_ms плюс малък марж, така че увеличаването му реално удължава времето за изчакване:

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

За /api/auto/ на защитена цел, първоначалното извикване (cold call) може да отнеме десетки секунди. Неговият timeout_ms покрива цялата стълбица и приема до 180000.

502 Upstream Unavailable

Симптом: API връща 502 с {"error": "Upstream unavailable"}, или 503 с {"error": "Backend service unavailable"}.

Причина: FourA е достигнал собствения си engine, но не е успял да използва отговора, обикновено защото инстанция се е рестартирала.

Решение: Опитайте отново с кратко забавяне. И двете се класифицират като service_error, и само success се таксува, така че повторният опит не ви струва нищо допълнително. Ако това продължи повече от минута или две, проверете статус страницата.

401 Authentication Errors

Симптом: Всяка заявка връща 401 Unauthorized.

Списък за проверка:

  1. Уверете се, че header-ът е X-API-Key: YOUR_API_KEY (а не Authorization: Bearer или Api-Key)
  2. Проверете за излишни интервали или нови редове във вашия API ключ
  3. Създайте нов ключ от Dashboard, ако текущият може да е компрометиран

400 Target Resolves to a Private/Reserved IP

Симптом: API връща 400 с Target <ip> resolves to a private/reserved IP преди заявката да напусне FourA.

Причина: Вашият url резолира до частен, loopback или запазен IP обхват (RFC 5735, RFC 6598 или запазени IPv6 блокове). FourA отказва тези цели, за да не може мрежата му да се използва за достигане до вътрешни хостове.

Решение: Извикайте публичен URL. Ако тествате, използвайте публична цел като https://example.com или https://httpbin.org/get. Ако вашата цел е услуга, която вие управлявате, първо я изложете на публично hostname.

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

no_eligible_proxy при използване на exitCountries

Симптом: /api/proxy/ извикване с exitCountries връща HTTP 200 с JSON обвивка за грешка:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

Причина: Текущият пул от proxy сървъри няма работещ изход, чиято видима за целта държава да съвпада с вашия списък с разрешени. FourA никога не преминава към неизискана държава, когато зададете exitCountries.

Решение: Запазете заявения обхват и опитайте отново по-късно. Пулът се опреснява приблизително на всеки десет минути, така че държава, която няма съвпадение сега, често получава такова в рамките на часа.

import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")

Разширявайте списъка с държави само ако изискванията за държава на вашия работен процес действително са се променили. Тихото превключване към други държави може да наруши географски зависимата логика по-надолу по веригата.

Тялото на response се връща като нечетлив текст

Симптом: Съответният response data (или body) съдържа нечетливи символи, когато целта използва кодировка, различна от UTF-8.

Причина: По подразбиране FourA автоматично декодира телата на response в UTF-8 въз основа на хедъра Content-Type на целта или HTML тага <meta charset>. Ако целта подаде грешна информация за своята кодировка, получавате нечетлив текст.

Решение: За бинарни данни (изображения, protobuf, raw аудио), задайте returnBuffer: true в съответния request. Тялото се връща като base64 буфер без приложено транскодиране.

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

За текстови цели, които декларират грешно своя charset, декодирайте суровите байтове сами: изтеглете с returnBuffer: true, декодирайте с base64, след което приложете правилния charset.

Неочакван HTML вместо JSON

Симптом: Очаквахте JSON от целевия сайт, но получихте HTML.

Причина: Целевата страница може да предоставя различно съдържание въз основа на headers.

Решение: Добавете Accept header и активирайте unblocker за реалистични browser headers:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

Можете също да зададете tryJsonData на true, за да може FourA автоматично да анализира JSON response.

Тялото е страница с предизвикателство, а не съдържание

Симптом: Извикването е успешно, status е 200, но data (или body) е проверка за ботове, а не желаната от вас страница.

Причина: Целта е изпълнила проверка за ботове, която FourA е срещнала, но не е успяла да премине. Това е посочено в съответния response: Single и Proxy връщат defense с solved: false, а Browser връща defenseSolved: false с доставчика в defenses.present.

Решение: Първо проверете defense.vendor, след това ескалирайте. Опитайте с различен профил на браузъра при Single, преминете към Proxy за различен изход или използвайте Browser, за да се изпълни JavaScript. Пълна справка за полетата и списък на доставчиците: Защити срещу ботове.

Добавете подниз validate.data.accept, който съдържа само реалната страница. Без него, страница с предизвикателство, върната с HTTP 200, се отчита като успех и вие разбирате за това по-късно в процеса, вместо при самото извикване.

Все още сте блокирани?

Ако никое от горните решения не работи:

  1. Проверете страницата за състояние за текущи инциденти
  2. Прегледайте request метриките си в Таблото за управление
  3. Свържете се с поддръжката на support@foura.ai с подробности за вашия request (включете X-FourA-Request-Id от неуспешния response)

Следващи стъпки

Обновено: 12 август 2026 г.