Често срещани проблеми

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

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

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

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

Решение: Преминете от стандартния endpoint към browser 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 или страници за верификация

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

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

Решение: Използвайте 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, за да дадете повече опити за ротация на проксито.

Грешка 403, върната от таргета, пристига като HTTP 200 с status: 403 в тялото. Грешка 403 при самото извикване, със заглавка X-FourA-Limit, е различно нещо: вижте 403 Not in Your Plan.

Грешки при изтичане на времето (Timeout)

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

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

Решение: Увеличете timeout_ms (по подразбиране е 15s за single, 30s за browser, 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 действително се появява на страницата. Печатна грешка прекратява извикването с checkText:<your text> not found.

403 Не е включено във вашия план

Симптом: API връща 403 с хедър X-FourA-Limit и reason от plan_limit_feature или plan_limit_premium.

{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

Причина: Вашият план не включва извикания endpoint или изпратения параметър. plan_limit_feature покрива изключен endpoint, а exitCountries, exitState, exitCity, exitAsn или exitOs без гео таргетиране. plan_limit_premium покрива exitClass: premium без премиум изходни точки, както и Proxy request, посочващ exit location, след като премиум трафикът ви е изчерпан. До целевия сървър изобщо не е изпращана заявка и нищо не е изразходвано.

Решение: Премахнете параметъра, извикайте endpoint, включен във вашия план, или надградете плана си. Разделът Limits & Features в Usage & Limits описва какво включва вашият план. Не опитвайте отново без промяна: заглавка Retry-After не е зададена, тъй като изчакването няма да промени резултата.

429 Твърде много заявки

Симптом: API връща 429.

Причина: Една от две проверки е отказала извикването, като отговорът показва коя точно. Ако съдържа header X-FourA-Limit, е достигнат лимит от вашия план: едновременни requests или requests в минута за този endpoint, Browser requests за деня, или кредитите или трафикът за отчетния период. Ако няма такъв header, споделеният минутен лимит на платформата за тази услуга е бил запълнен, което е свързано с общия трафик на FourA, а не с вашия.

Решение: Първо проверете X-FourA-Limit. Изчакайте, ако лимитът се нулира след няколко секунди, и спрете, ако не е така. Лимитите на плана, които се изчистват с изчакване, записват секундите в заглавката Retry-After и в retry_after_seconds; споделеният лимит ги записва в retryAfter:

import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

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:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 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"}
)

Ако заглавката съдържа plan_limit_concurrency или plan_limit_rate, решението е да ограничите броя на отворените заявки и броя на стартираните за минута, вместо да опитвате по-агресивно повторно изпълнение. Повторното изпращане на отхвърлена партида веднага води до повторно отхвърляне на цялата партида. Отхвърлените заявки не се броят към лимита за минута, но ако продължат да пристигат с повече от два пъти над него, отхвърлянията преминават в период на изчакване (cooldown): тялото на 429 съдържа cooldown: true и изисква да направите пауза за 30 секунди (retry_after_seconds: 30). Паралелно изпълнение на заявки показва шаблона, а Usage & Limits в Dashboard показва броячите в реално време редом с вашите лимити.

503 Услугата е недостъпна

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

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

  1. Услугата е с изчерпан капацитет. FourA вече изпълнява максималния брой едновременни заявки на този engine, изчислен за целия трафик, а не само за вашия. Service at capacity в полето error. Обикновено се изчиства за секунди.
  2. Услугата е временно спряна. Извършва се техническа поддръжка. Service disabled в полето error.
  3. FourA временно не може да провери вашия ключ. API key check temporarily unavailable в полето error с Retry-After: 5. Вашият ключ е наред.

И трите случая включват поле retryAfter в отговора. Нито един от тях не е лимит на плана: лимитите на собствения ви план винаги отговарят със заглавка X-FourA-Limit при 403 или 429, никога с 503.

Решение: Изчакайте 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):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Грешка 503 при запълнен капацитет означава, че FourA е зает, така че изчакването и повторният опит са цялото решение. Ако вместо това заявката е отказана с 429 и X-FourA-Limit, проблемът е във вашия контрол: намалете броя на паралелните requests във вашия пайплайн.

504 Изтекло време за отговор отгоре (Upstream Timeout)

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

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

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

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

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

Когато самият /api/auto/ изчерпи този лимит, извикването все пак връща HTTP 200. Тялото съдържа error, което започва с time budget exhausted, а status обикновено е 504 (по-ранен неуспешен опит може вместо това да остави своя собствен статус там). Увеличете timeout_ms или опитайте отново.

502 Upstream не е наличен

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

Причина: FourA не успя да се свърже със своя собствен engine (Upstream unavailable) или engine не върна използваем отговор (Backend service unavailable), обикновено поради рестартиране на инстанция. При /api/browser/ страницата чака до 10 секунди за свободен браузър, когато всички са заети, и страница, която все още чака след това, се връща като това 503.

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

401 Грешки при автентикация

Симптом: Всяка заявка връща 401 Неоторизиран достъп (Unauthorized).

Контролен списък:

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

400 Невалидна заявка

Симптом: Извикване на POST /api/single/, /api/proxy/ или /api/browser/ връща 400 с {"error": "Invalid request: <field>: <reason>; ..."}.

Причина: Поле в тялото на вашата заявка липсва, е от грешен тип или е извън допустимия диапазон. Съобщението посочва всяко поле, което не е могло да бъде прието, и причината за това, до максимум пет полета, последвани от and N more, когато има и други. Нищо не е изтеглено, резултатът е client_error и не се изразходват кредити.

Решение: Коригирайте посочените полета и изпратете заявката отново. Същото тяло ще доведе до същия отговор 400, така че не правете повторен опит без промени. В справочника за endpoint-и са изброени всички полета с техните типове и ограничения. При /api/auto/ същата грешка се връща като HTTP 200 с status: 400 и причината във error.

400 Целевият адрес се разрешава до частен или резервиран IP адрес

Симптом: API връща 400 с Refusing to fetch <target>: target resolves to a private or reserved IP range, преди заявката да напусне FourA.

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

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

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

Име на хост, което не може да бъде намерено чрез DNS, не се отхвърля. Заявката се връща като HTTP 200 с status: 0 и причината (could not resolve <host>: <reason>), както при всяка цел, до която FourA няма достъп, и не се таксува.

400 Интервал в URL

Симптом: Single, Proxy или Auto връща 400 с invalid URL: it contains a space; encode it as %20 (the URL as sent: "..."), преди заявката да напусне FourA.

Причина: URL адресът съдържа интервал или контролен символ, обикновено линк, взет от страница точно както е написан (javascript: void(0), линк за споделяне с текст в него). Нищо не се извлича, резултатът е client_error и не се изразходват кредити.

Решение: Кодирайте URL адреса, преди да го изпратите (интервалът е %20), и пропускайте линкове, които не са страници, като тези с javascript:. Browser извлича такъв URL по начина, по който го прави Chrome.

400 Целта е самият API на FourA

Симптом: API връща 400 с Refusing to fetch <url>: that is the FourA API itself, not a page., преди заявката да напусне FourA.

Причина: Вашият url сочи към api.foura.ai или eu.api.foura.ai. Кроулър обикновено прави това, когато преобразува относителен линк от страница спрямо URL адреса на API вместо спрямо собствения URL адрес на страницата, така че /category/news/ се превръща в https://eu.api.foura.ai/category/news/. Нищо не се извлича и не се изразходват кредити.

Решение: Преобразувайте всеки линк спрямо URL адреса на страницата, от която идва, преди да го изпратите, например с urljoin(page_url, href) в Python. Inspect endpoint (/inspect) е единственият адрес на хоста на API, който можете да извличате чрез FourA.

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 pool няма работещ изход, чиято видима за целта държава съвпада с вашия allowlist. Стандартният pool никога не преминава към незаявена държава, когато зададете exitCountries. Без exitCountries същата ситуация връща {"error": "Failed"}: FourA няма наличен изход за опит, затова опитайте отново след няколко секунди.

Заявка, която посочва локация на изхода (exitState, exitCity, exitAsn, exitOs или exitLifetimeMin, заедно с exitClass: premium), се изпълнява само през premium изходи. Когато FourA няма останал premium изход за нея, извикването завършва с "error": "No premium exit answered for this request" и същия code: no_eligible_proxy.

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

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

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

Отказан профил на браузър

Симптом: Извикването се връща с unknown profile '<id>', no profile matches browser=... или browser profile selection requires unblocker:true.

Причина: Изпратеният profile, browser, os или version не е в каталога или сте изпратили такъв с unblocker: false.

Решение: Прочетете GET /api/profiles за текущия каталог, изберете от него и оставете unblocker включен, когато избирате браузър.

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

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

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

Решение: За двоични данни (изображения, protobuf, сурово аудио), задайте returnBuffer: true в заявката. Тогава Single и Proxy връщат data като обект, съдържащ суровите байтове, {"type": "Buffer", "data": [<byte values>]}, без да се прилага транскодиране на кодирането.

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

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

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

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

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

Решение: Добавете Accept header и активирайте unblocker за реалистични браузърни 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 responses.

Body съдържа страница с проверка, а не съдържание

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

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

Решение: Първо проверете defense.vendor, след което ескалирайте. Опитайте различен browser profile при Single, преминете към Proxy за различен exit или използвайте Browser, за да се изпълни JavaScript. Пълен списък с полета и доставчици: Site checks.

Добавете подниз validate.data.accept, който се съдържа единствено в истинската страница. Страница за проверка, разпозната от FourA, никога не се счита за успех: тя се връща със заглавка X-FourA-Check-Page и не се таксува. Без validate, неразпозната от FourA страница за проверка, върната с HTTP 200, се счита за успешна и разбирате за това на по-късен етап, а не при самото извикване.

Все още имате проблем?

Ако никое от горните решения не помогне:

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

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

  • Error Handling: Справка за кодовете за грешки на API
  • Rate Limits: Всички лимити на планове и платформа, с полета
  • Request Outcomes: Как изходите класифицират случилото се
  • Site checks: Какво показва полето defense
  • Choosing the Right Endpoint: Изберете най-добрия подход за вашата цел
  • Dashboard Overview: Мониторинг на вашите заявки
Обновено: 13 ноември 2026 г.