API грешки
Как да обработвате грешки от FourA API.
Формат на отговора за грешка
API връща плоски JSON обекти за всички грешки. Няма вложен обект error. Когато грешката съдържа машинночетим код, той е поле от първо ниво: reason при лимит на плана, code при извикване на proxy без валиден изход.
{
"error": "Invalid API key"
}
Някои грешки включват допълнителни полета като status, service, retryAfter, current или limits на най-горно ниво:
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": { "concurrency": 12, "rpm": 3000 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Проследяване на request
Всеки API response (успешен или с грешка) включва X-FourA-Request-Id header с UUID за това повикване, с изключение на body, което FourA изобщо не може да прочете (деформиран JSON или body над 100 KB): то се отхвърля преди присвояването на ID. Записвайте го в логовете от ваша страна. Ако трябва да попитате поддръжката какво се е случило с конкретен request, това ID ни позволява да го открием.
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: Невалидна заявка (Bad Request)
Тялото на заявката не съдържа задължителни полета, съдържа невалидни стойности или посочва цел, която API отказва да извлече.
Тяло, което не е JSON обект или масив, се счита за невалиден JSON и връща Invalid JSON in request body, показано по-долу.
При Single, Proxy Finder и Browser, поле, което липсва, е от грешен тип или е извън допустимия диапазон, се посочва в съобщението като <field>: <reason>. Вложените полета се обединяват с точки (validate.status.accept). Извеждат се до пет проблема, разделени с ; , а всичко след това завършва съобщението като and <n> more:
{
"error": "Invalid request: url: Invalid input: expected string, received undefined"
}
Това е client_error и не се таксува. Auto вместо това съобщава за поле, което не може да приеме, в рамките на HTTP 200, както е описано в „Разчитане на неуспешни заявки от /api/auto/“ по-долу.
Същият статус 400 обхваща и SSRF защитата. Ако вашият url се резолва до частен, loopback или друг резервиран IP диапазон (RFC 5735, RFC 6598, IPv6 резервирани блокове), заявката се отхвърля, преди да напусне мрежата на FourA:
{
"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 вместо спрямо този на самата страница:
{
"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> е целевият адрес точно както сте го изпратили. Страницата Inspect е единственото изключение: FourA все пак извлича https://eu.api.foura.ai/inspect вместо вас.
URL с интервал или контролен символ в него също получава 400 при Single, Proxy Finder и Auto, преди да бъде извлечено каквото и да било или да бъде начислена такса. Копиран от страница линк често съдържа такъв знак (javascript: void(0), линк за споделяне с интервали в текста си). Кодирайте го, като интервалът става %20. Browser извлича такъв URL по начина, по който го прави Chrome:
{
"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 отговор (достигнат лимит за пренасочвания, timeout при връзка или четене, reset), също се връща като HTTP 200, с error и total_time и без status: вижте Request Outcomes.
При Single response body над 128 MB след декодиране спира дотам. Заявката се връща като HTTP 200 с "error": "Response body exceeds the 128 MB limit" и не се таксува.
Невалиден 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 |
ID то се декодира успешно, но вече не съответства на активен изход. Изберете нов. |
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 ключ липсва или е невалиден.
Липсващ ключ:
{
"error": "Missing API key. Include X-API-Key header."
}
Невалиден ключ:
{
"error": "Invalid API key"
}
Решение: Проверете дали вашият X-API-Key header съдържа валиден ключ. Генерирайте нов ключ от Dashboard, ако е необходимо.
Грешка 401 винаги означава, че FourA е проверил вашия ключ и го е отхвърлил. Когато FourA не може да провери ключ за няколко секунди, връща 503 API key check temporarily unavailable (вижте по-долу), никога 401.
403: Не е включено във вашия план
Заявката изисква endpoint или параметър, който вашият план не включва. Отговорът задава X-FourA-Limit и поставя същия код в тялото под reason:
{
"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 и полетата за локация на изход при план без геотаргетиране, и plan_limit_premium за exitClass: premium при план без премиум изходи, или за exit location без останал премиум трафик. Стрингът error посочва съответния endpoint или параметър.
Грешка 403 от FourA никога не се отнася за целевия сайт: с целта изобщо не е осъществен контакт. Върната от целта грешка 403 пристига като HTTP 200 с status: 403 в тялото на отговора.
Решение: Премахнете параметъра, извикайте endpoint, включен във вашия план, или надградете плана си. Не се задава Retry-After, тъй като изчакването няма да промени резултата. Нищо не е изразходено: резултатът е rate_limit, а се таксува само success.
413: Твърде голям полезен товар
JSON тялото на заявката е по-голямо от допустимото за FourA (100 KB). Отговорът не е JSON и не съдържа X-FourA-Request-Id, тъй като тялото се отхвърля преди да бъде прочетено.
Решение: Изпратете по-малък data payload. Нищо не е изразходено.
429: Ограничен брой заявки
Две различни проверки връщат 429 и те не съдържат едни и същи полета.
Собствените лимити на вашия план. Отговорът задава заглавка X-FourA-Limit, посочваща кой лимит е отказал повикването, и поставя същия код в тялото под reason:
{
"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 и в заглавката Retry-After, никога в retryAfter. plan_limit_browser_daily не съдържа нито едно от двете, тъй като лимитът се възстановява в полунощ UTC, а не след секунди. Нищо не е изразходвано: резултатът е rate_limit и се таксува само success.
Споделеният лимит на платформата. Няма заглавка X-FourA-Limit, а времето за изчакване е в retryAfter:
{
"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 съдържа отговорът. При concurrency или rate limit ограничете броя на отворените заявки, вместо да изпращате отново отказаната партида. При дневен лимит или лимит за период на фактуриране спрете изпълнението. Вижте Rate Limits за всяко поле и Run Requests in Parallel за модела на работа.
500: Сървърна грешка
Възникна проблем от наша страна.
Решение: Опитайте отново заявката след кратко забавяне. Ако грешката продължава, проверете status page или се свържете с поддръжката, като предоставите X-FourA-Request-Id от неуспешния отговор.
502: Upstream сървърът е недостъпен
FourA не успя да получи отговор от собствения си engine (Upstream unavailable: връзката пропадна) или получи такъв, който не можа да разчете (Malformed JSON from backend).
{
"error": "Upstream unavailable",
"details": "..."
}
Решение: Опитайте отново с кратко изчакване. Проблемът е от наша страна, така че не ви струва нищо: резултатът е service_error и се таксува само success.
504: Изтече времето за изчакване към upstream
Двигателят не приключи в рамките на предвиденото време за тази request заявка.
{
"error": "Upstream timeout",
"details": "the backend did not finish inside the time budget for this request"
}
Грешка 504 е свързана с това колко време е отнела работата, а не с вашия ключ, вашите параметри или вашето proxy. Бавни целеви сайтове, първоначално решаване на трудни проверки и големи страници са обичайните причини.
Решение: Увеличете timeout_ms в заявката (Single приема до 120000, Browser до 120000, Auto до 180000) или опитайте отново. FourA изчаква зададения от вас лимит от време плюс малък марж, така че заявяването на повече време действително осигурява повече време.
503: Услугата е изключена или капацитетът е запълнен
Грешка 503 означава, че услугата временно не е достъпна поради поддръжка или лимитът за едновременни заявки на платформата е изчерпан. И двата случая съдържат едни и същи ключове: error, status, service, retryAfter, current и limits. Разграничавайте ги по низа error, а не по това кои полета присъстват.
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Service disabled означава поддръжка, а current показва 0 и за двата брояча, тъй като заявката е отхвърлена, преди да бъде измерено каквото и да е. Service at capacity е формата за паралелност, като там current съдържа реалното използване на платформата. Вижте Rate Limits за тази структура.
Решение: Изчакайте retryAfter секунди и опитайте отново. Страницата за статус показва активните прозорци за поддръжка.
Третият вид 503 няма retryAfter. Това означава, че енджинът зад вашия endpoint не е могъл да приеме извикването ви: рестартирал се е, възникнала е грешка от страната на FourA преди изпълнението на вашата заявка или (при Browser) всички браузъри са останали заети през всичките 10 секунди, които страницата изчаква за свободен такъв. backend_status е собственият статус на енджина, а detail е началото на неговия отговор:
{
"error": "Backend service unavailable",
"backend_status": 503,
"detail": "..."
}
Това е service_error и не се таксува. Опитайте отново след секунда или две. Невалидна сама по себе си заявка никога не стига дотук: тя получава 400 с посоченото поле.
Четвърти 503 означава, че FourA временно не е успял да потвърди вашия API key, например по време на превключване на базата данни. Проблемът не е във вашия ключ и нищо не е изпълнено. Той съдържа Retry-After: 5 и същото време за изчакване в retryAfter:
{
"error": "API key check temporarily unavailable",
"status": 503,
"retryAfter": 5
}
Не се таксува. Опитайте отново след retryAfter секунди. Ключ, който FourA е потвърдил през последните 10 минути, продължава да работи при такъв момент, така че този отговор е рядък.
Разчитане на грешки от /api/auto/
POST /api/auto/ отговаря с HTTP 200 винаги, когато стълбата се е изпълнила, дори когато всяко стъпало се е провалило. Реалният резултат се намира в body:
{
"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 посочват какво е изпратило извикването. Вижте Защо автоматично извикване е било неуспешно. Поле в заявката, което Auto не може да приеме (например timeout_ms под 5000 или над 180000), се връща по същия начин: HTTP 200 с "status": 400 и причината в error, преди да бъде направен какъвто и да е опит и без таксуване.
Затова не разклонявайте логиката според транспортния статус за Auto. Вместо това четете status и error от тялото. Истински статус, различен от 200, от /api/auto/ означава, че FourA е отхвърлил извикването преди стартирането на поредицата от опити или не е могъл да го завърши: 400 (невалиден JSON, частен или резервиран адрес на целта, или цел на собствения API хост на FourA), 401, 413, 502, 503 или 504. Един лимит на плана се връща директно на входа: exitClass: premium при план без premium exits получава 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 хедър, както директният отказ:
{
"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).
Неуспешни отговори от страна на целта при 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 покрива пълната таксономия.
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-* или друг charset, деклариран в хедъра Content-Type или в HTML <meta charset> таг, получавате изчистен UTF-8 низ в полето data (single, proxy) или body (browser).
За бинарни данни (изображения, protobuf, сурово аудио), задайте returnBuffer: true в заявката. Тогава Single и Proxy връщат data като обект, съдържащ суровите байтове, {"type": "Buffer", "data": [<byte values>]}, без прилагане на транскодиране на кодировката.
Стратегия за повторни опити
Практична политика за повторни опити:
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")
Неуспешните proxy заявки съдържат отчет
POST /api/proxy/ извикване, което изчерпи опитите си, се връща като HTTP 200 с error обвивка, а не като HTTP error код. Текстът на грешката е кратък и винаги в един и същ формат, затова заедно с него се предоставя и attemptReport обект с броя опити:
{
"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 заявката изчерпа опитите си.
Свързани
- Rate Limits: Лимити на плана, паралелност и детайли за RPM
- Паралелно изпълнение на заявки: Ограничаване в рамките на позволената паралелност за плана
- Резултати от заявки: Разяснение на седемте възможни резултата
- Често срещани проблеми: Симптоми, причини, решения
- Проверки на сайта: Когато съдържанието е challenge страница вместо грешка
- Защо proxy заявката изчерпа опитите си: Разчитане на
attemptReport