Лимити на заявките
Всяка FourA API заявка преминава през три проверки, преди да достигне до даден engine: лимитите на вашия собствен план, след това споделения лимит на платформата за целия трафик и накрая споделения лимит на платформата за endpoint адреса, който сте извикали. Всяка проверка може самостоятелно да отхвърли заявка и всяка връща различно тяло на отговора.
Трите проверки по ред
- Лимити на плана. Какво позволява вашият собствен план: кои endpoint адреси и параметри включва, колко заявки могат да се изпълняват едновременно за endpoint, колко в минута, колко браузърни заявки на ден, както и наличните кредити и трафик (bandwidth) за периода на фактуриране.
- Глобален лимит на платформата. Всичко, което API хостът, който сте извикали, обработва в този момент, независимо към кой endpoint е насочен трафикът. Отхвърляне тук връща
"service": "api". - Лимит на платформата за endpoint. Трафикът към Single, proxy или browser услугата, която сте извикали.
Вашият собствен план се оценява първи и тази последователност е договореност, а не детайл на имплементацията. Споделените лимити са общ ресурс, така че заявка, която платформата така или иначе щеше да отхвърли, не трябва да ги изразходва, докато бива отхвърлена. Акаунт, изпращащ много повече от позволеното от плана му, бива спрян, преди да засегне ресурсите, от които се възползват останалите.
Проверки 2 и 3 отчитат общия трафик на FourA, а не вашия. Приемайте отхвърляне от някоя от тях като "FourA е заета", а не като "изпратихте твърде много". Проверка 1 се отнася само за вашия акаунт и нищо друго в платформата не ѝ влияе.
Отхвърляне от която и да е споделена проверка възстановява на акаунта ви всичко, което допускането ѝ е отчело, както минутното разпределение, така и дневния слот за браузър, тъй като заявката така и не е достигнала backend. Това не се отчита и към паузата за повторен опит, описана в Заявки в минута: капацитетът на FourA я е отхвърлил, а не вашият план.
POST /api/auto/ няма собствен слот. Подповикванията Single, Proxy и Browser, които прави вместо вас, преминават през трите проверки като всяка друга заявка, така че паралелна партида от auto повиквания се отчита спрямо вашия план чрез нейните подповиквания. (Броят на заявките и процентът на успеваемост отчитат самото auto повикване веднъж; подповикванията се показват като негови опити.)
Лимити на плана
При надвишаване на лимит на плана се връща X-FourA-Limit заглавка, посочваща кой лимит е отхвърлил повикването. Същият код се намира в тялото под reason, така че можете да добавите логическо разклонение без да четете заглавките. Всяко тяло при отхвърляне от лимит на плана съдържа error, reason и documentation; останалите полета зависят от лимита.
X-FourA-Limit |
Статус | Какво е изчерпано |
|---|---|---|
plan_limit_feature |
403 | Endpoint адресът, който сте извикали, или параметърът exitCountries, exitState, exitCity, exitAsn или exitOs не е включен във вашия план |
plan_limit_premium |
403 | exitClass: premium не е включен във вашия план или proxy заявка посочва exit location без оставащ премиум трафик |
plan_limit_concurrency |
429 | Едновременни заявки към този endpoint |
plan_limit_rate |
429 | Заявки в минута към този endpoint |
plan_limit_browser_daily |
429 | Браузърни заявки за деня |
plan_limit_credits |
429 | Таксувани кредити за отчетния период |
plan_limit_bandwidth |
429 | Трафик за отчетния период |
Стойностите за всеки лимит зависят от вашия план, а разделът Limits & Features в Usage & Limits ги показва до текущото ви потребление. Не ги задавайте твърдо в кода: всеки отказ връща прага, който го е предизвикал.
Отхвърлената заявка не изразходва ресурс. Резултатът е rate_limit и се таксува само success.
Endpoint или параметър извън плана
Грешка 403 с plan_limit_feature означава, че заявката изисква функционалност, която планът не включва. Проверката се извършва преди отчитането, така че отхвърлената заявка не засяга вашите rate limit или дневни броячи.
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
Същият код и статус се връщат при POST /api/proxy/ извикване, което задава exitCountries, exitState, exitCity, exitAsn или exitOs при план без геотаргетиране. Низът error посочва параметъра:
{
"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"
}
plan_limit_premium има същата структура за exitClass: premium при план без premium изходи. План, който включва premium изходи, но е изразходвал premium трафика за текущия период, не бива отказан, освен ако Proxy заявка не посочва конкретна изходна локация: заявката се обслужва от стандартния pool и отговорът отчита exitClass: standard. Нито един от двата случая не изразходва premium изход. Вижте exitClass.
Нито един от двата 403 статуса не задава Retry-After. Изчакването няма да промени резултата.
Едновременни заявки
Паралелността се отчита за всеки endpoint поотделно: вашият план съдържа един лимит за Single, един за Proxy и един за Browser. Заявката, която надвиши лимита, се връща като 429 с Retry-After: 1:
{
"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
}
in_flight отчита и отказаната request, така че показва поне с едно повече от limit.
Решението е да ограничите собствения си паралелизъм, вместо да опитвате отново по-агресивно. Отговорът на 429 чрез незабавно повторно изпращане на същия batch води до пореден 429 за всяко повикване в него. Вижте Run Requests in Parallel за готов работещ модел.
Requests в минута
Single и Proxy разполагат с лимит за минута, измерван на база плъзгащ се едноминутен прозорец. Само приетите requests се броят към него: отказаната request се изважда обратно, така че акаунт, който постоянно изисква малко над лимита си, получава пълния си разрешен обем, вместо да му бъде отказано почти всичко.
{
"error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 613,
"retry_after_seconds": 17
}
retry_after_seconds е времето, след което още една request ще бъде допусната, ако междувременно не изпращате нищо друго: поне 1 секунда и най-много 120. Retry-After header носи същата стойност.
Повторният опит за отхвърлени requests по-бързо от това има собствено правило. Когато отхвърлените от този лимит requests в рамките на плъзгащата се минута надвишат два пъти лимита, повикването се отхвърля с 30-секундна пауза вместо това:
{
"error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 540,
"refused_last_minute": 1250,
"cooldown": true,
"retry_after_seconds": 30
}
Отказите по време на паузата не се броят, така че паузата приключва от само себе си с напредването на минутата, дори за клиент, който продължава да прави опити. За да различите паузата от стандартния лимит, четете cooldown вместо текста на error.
Browser заявки на ден
Browser няма лимит за минута. Лимитът на неговия план е брой browser заявки на ден, отчитани от полунощ UTC, и броячът включва всяка допусната browser заявка, а не само успешните. Повикване към Browser, което се провали от страна на FourA с нула кредити, като например 503 Backend service unavailable, възстановява своя дневен слот. Отговорите от Browser и Auto, които не са отказани от вашите лимити, носят броя и лимита в заглавките X-FourA-Browser-Used-Today и X-FourA-Browser-Limit-Per-Day: вижте Response Headers.
{
"error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
"reason": "plan_limit_browser_daily",
"documentation": "https://foura.ai/prices",
"limit_per_day": 300,
"used_today": 301
}
Този отказ не съдържа нито retry_after_seconds, нито Retry-After header, тъй като изчакването е часове, а не секунди. Приемете го като спиране и планирайте следващото изпълнение за полунощ UTC.
Кредити за периода на таксуване
Зачитат се само таксуваните кредити, което означава само успешните заявки. Когато таксуваната обща сума достигне наличните за вас кредити за този период, следващите заявки се отхвърлят, докато периодът не се нулира или не закупите допълнително.
{
"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"
}
hard_stop е броят фактурирани кредити, при достигането на който заявките спират за този период. Четете го от тялото на отговора, вместо да го изчислявате: той вече включва всички кредити, закупени в допълнение към плана.
Трафик за периода на фактуриране
Плановете с лимит на трафика отказват заявки, след като стандартният трафик за периода го достигне. Премиум трафикът има отделен лимит и не се зачита към това ограничение. Закупеният трафик се отчита еднакво с включения в плана трафик, а низът error показва какво е налично за вас, а не само включеното в плана.
{
"error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
"reason": "plan_limit_bandwidth",
"documentation": "https://foura.ai/prices",
"used_bytes": 53687091200,
"limit_bytes": 53687091200,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
И при двата лимита за период, retry_after_seconds е ограничен до 24 часа; resets_at е точният момент, в който периодът се подновява.
Полета за лимити на плана
| Поле | Тип | Налично при | Описание |
|---|---|---|---|
error |
string | всички | Четливо съобщение, включващо стойността, към която сте ограничени |
reason |
string | всички | plan_limit_ плюс името на лимита. Същата стойност като хедъра X-FourA-Limit. |
documentation |
string | всички | Връзка към страницата с планове |
retry_after_seconds |
number | concurrency, rate, credits, bandwidth | Колко време да се изчака. Същата стойност като хедъра Retry-After. |
limit |
number | concurrency | Едновременни заявки, разрешени от плана за този endpoint |
in_flight |
number | concurrency | Заявки, изпълняващи се на този endpoint за вашия акаунт, включително отказаната |
limit_per_minute |
number | rate | Заявки в минута, разрешени от плана за този endpoint |
current_rate |
number | rate | Заявки, отчетени в плъзгащия се едноминутен прозорец, включително отказаната |
refused_last_minute |
number | rate pause | Заявки, отказани от лимита за минута в плъзгащия се прозорец. Само при 30-секундната пауза. |
cooldown |
boolean | rate pause | true при 30-секундната пауза заради твърде бързи повторни опити. Липсва при обикновен отказ за превишен лимит в минута. |
limit_per_day |
number | browser daily | Заявки с браузър, разрешени от плана на ден |
used_today |
number | browser daily | Заявки с браузър, отчетени днес, включително отказаната |
used |
number | credits | Таксувани кредити до момента за този период |
hard_stop |
number | credits | Таксувани кредити, при достигането на които заявките спират за този период |
used_bytes |
number | bandwidth | Стандартен трафик до момента за този период, в байтове. Premium трафикът не е включен. |
limit_bytes |
number | bandwidth | Налични байтове за този период |
resets_at |
string | credits, bandwidth | ISO 8601 времеви маркер за края на периода |
Лимитите на плана използват retry_after_seconds. Лимитите на платформата по-долу използват retryAfter. Помощната логика за повторни опити трябва да чете и двете, или да чете хедъра Retry-After, който се задава от лимитите на плана, както и от 503 API key check temporarily unavailable (вижте Грешки).
Лимити на платформата
Проверките на платформата проследяват две неща за всяка услуга и още едно за всички тях общо:
- Concurrency: колко заявки изпълнява FourA едновременно.
- RPM: колко заявки е приел FourA през последните 60 секунди.
И двата брояча са споделени между всички, използващи тази услуга. current и limits в отговорите по-долу описват платформата, а не вашия акаунт. Ако искате вашите собствени стойности, прочетете in_flight от отговор за лимит на плана или отворете Usage & Limits в dashboard.
429: Надвишен RPM
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": {
"concurrency": 12,
"rpm": 3000
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
Услугата достигна разрешения брой заявки за последната минута. Изчакайте retryAfter секунди.
503: Надвишен брой едновременни заявки
{
"error": "Service at capacity",
"status": 503,
"service": "proxy",
"retryAfter": 2,
"current": {
"concurrency": 500,
"rpm": 1200
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
Услугата изпълнява толкова заявки едновременно, колкото е разрешено. Това се изчиства за секунди.
Изключена услуга
Когато дадена услуга е временно спряна за поддръжка, API връща 503 с различно съобщение за грешка:
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Това не е rate limit. Услугата е временно недостъпна. Проверете стойността на retryAfter и опитайте отново след съответния брой секунди. Това обикновено се разрешава в рамките на минути.
И двете 503 структури съдържат едни и същи ключове, така че разклонявайте логиката според низа error, а не според наличните полета. Service disabled означава поддръжка, Service at capacity означава concurrency.
При структурата за поддръжка current.concurrency и current.rpm винаги са 0: заявката е била отхвърлена, преди да бъде измерено каквото и да е.
Полета за лимити на платформата
| Поле | Тип | Описание |
|---|---|---|
error |
string | Човешки четимо съобщение за грешка |
status |
number | Код за състояние на HTTP (429 или 503) |
service |
string | Коя услуга е отказала повикването: single, proxy, browser или api |
retryAfter |
number | Препоръчително време за изчакване в секунди преди повторен опит |
current.concurrency |
number | Заявки, изпълнявани от услугата за всички клиенти към момента на отказа |
current.rpm |
number | Заявки, поети от услугата за всички клиенти през последните 60 секунди |
limits.maxConcurrency |
number | Споделен лимит за concurrency на услугата |
limits.maxRpm |
number | Споделен лимит на услугата за минута |
Обработване на всеки отказ с един помощен метод
Retry-After е зададен при лимитите на плана, за които си струва да се чака, retry_after_seconds е в техните тела, а retryAfter е в телата на платформата. Прочетете и трите в този ред и прекратете при лимитите на плана, които никакво чакане няма да изчисти:
import time
import requests
# Plan limits that a short wait never clears.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def wait_seconds(resp, attempt):
header = resp.headers.get("Retry-After")
if header and header.isdigit():
return int(header)
try:
body = resp.json()
except ValueError:
return 2 ** attempt
return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
def fetch(url, api_key, max_retries=5):
for attempt in range(max_retries):
resp = requests.post(
"https://eu.api.foura.ai/api/single/",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={"method": "GET", "url": url},
)
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")
if resp.status_code in (429, 503):
time.sleep(wait_seconds(resp, attempt))
continue
return resp
raise RuntimeError("Max retries exceeded")
Дневен лимит не се възстановява с часове, а периодният лимит не се възстановява с дни, така че ги третирайте като спиране, а не като изчакване. Прочетете resets_at от тялото, ако искате да планирате следващото стартиране.
Съвети
- Ограничете броя на паралелните заявки (in flight), вместо да повтаряте отхвърлен пакет. Бурята от повторни опити превръща една грешка 429 в множество.
- Първо прочетете
X-FourA-Limit. Той ви показва в един низ дали лимитът е ваш или на платформата, като нито един отказ от страна на платформата не го задава. - Не хардкодвайте числата. Всеки отговор за лимит на плана носи тавана, който го е отхвърлил, а Usage & Limits показва всички тях.
retryAfterпри лимитите на платформата е фиксиран според вида: 2 секунди за едновременност, 5 за RPM, 60 за поддръжка.- Съпоставяйте по
error, за да различите двата вида 503. И двете структури съдържатcurrentиlimits, така че проверка "налични ли са тези полета?" интерпретира поддръжката като проблем с едновременността. - 403 с
X-FourA-Limitсе отнася за вашия план, а не за целевия сайт. Целевият сайт изобщо не е отговорил.
Портът на проксито има собствени лимити
Всичко по-горе се отнася за JSON API. Трафикът, който изпращате през proxy.foura.ai, се подчинява на отделен набор от лимити на плана, в различна мерна единица: едновременно отворени тунели, отваряния на тунели за минута и стандартен трафик за периода на фактуриране. Тези откази пристигат като HTTP статус с X-Foura-Error хедър вместо като JSON тяло, тъй като CONNECT няма тяло, в което да се постави такъв. Вижте Proxy Port за таблицата със статуси и How Your Plan Is Metered за това от кой пул се приспадат гигабайтите на порта.
Свързани
- Run Requests in Parallel: Практически модел за ограничена едновременност
- Usage & Limits: Всеки лимит на плана редом с вашето текущо потребление
- API Endpoints: Пълна документация на параметрите
- Error Handling: Всички типове грешки и отговори
- Response Headers:
X-FourA-Limit,Retry-Afterи останалите - Troubleshooting: Често срещани проблеми и решения