# Response Headers

> URL: https://foura.ai/bg/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

Всеки response от FourA API съдържа малък набор от персонализирани headers. Те са полезни за tracing, поддръжка, равняване на сметките и последващ анализ.

## Headers, задавани от FourA

| Header | Задава се при | Описание |
|--------|--------|-------------|
| `X-FourA-Request-Id` | Всеки `/api/*` response, включително грешки и 401s, с изключение на body, което FourA изобщо не може да прочете (`400 Invalid JSON in request body`, `413`), което се отхвърля преди присвояване на ID | UUID, идентифициращ този request. Записвайте го в логовете от ваша страна. |
| `X-FourA-Credits` | Всеки `/api/*` response, достигнал до backend-а | Изразходвани кредити за това извикване. Връща се при успех и при грешка (работата е извършена и в двата случая). |
| `X-FourA-Limit` | Всеки `403` или `429`, предизвикан от някой от лимитите на вашия план | Кой лимит е отхвърлил извикването: `plan_limit_`, последван от `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits` или `bandwidth`. |
| `Retry-After` | `429` при лимит на плана, които изчакването изчиства (concurrency, rate, кредити, трафик), и 503 `API key check temporarily unavailable` | Секунди за изчакване като цяло число. Съответства на `retry_after_seconds` в body при лимит на плана и на `retryAfter` при 503. |
| `X-FourA-Exit-Class` | Всяко `/api/proxy/` или `/api/auto/` извикване, посочило `exitClass` и доставило страница, и всяко Single или Browser извикване, обслужено през премиум изход | `premium` или `standard`: класът на изхода, доставил тялото. Неуспешно Proxy извикване не доставя нищо и не носи такъв. |
| `X-FourA-Browser-Used-Today` | Всеки `POST /api/browser/` отговор, който лимитите на плана ви не са отхвърлили, и всеки `POST /api/auto/` отговор, чийто ladder е изпратил request, който те не са отхвърлили | Browser заявки, преброени днес за вашия акаунт: вижте по-долу. |
| `X-FourA-Browser-Limit-Per-Day` | Същите отговори, когато планът ви задава дневен брой | Browser заявки, разрешени от вашия план на ден. |
| `X-FourA-Check-Page` | Single, Proxy Finder и Browser отговори, чието HTTP 200 body е страница за проверка за ботове или отказ, която FourA разпознава | Името на страницата, например `amazon-captcha`. Такъв request не се таксува: вижте [Request Outcomes](https://foura.ai/docs/api/outcomes). |
| `Content-Type` | Всеки response | Винаги `application/json` за обвивката. content-type на целта се връща в полето `headers` на обвивката. |

## X-FourA-Request-Id

Всяко извикване към `POST /api/auto/`, `POST /api/single/`, `POST /api/proxy/` или `POST /api/browser/` се маркира с UUID. Този header се задава дори при неуспешна автентикация, така че можете да проследявате и неправилно конфигурирани извиквания.

```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
X-FourA-Credits: 2
Content-Type: application/json
...
```

### Кога да го използвате

- **Тикети за поддръжка**: включете ID на заявката (request ID) и ние ще открием точния call в нашите записи.
- **Вашите собствени логове**: съхранявайте го до реда в логовете на вашето приложение. Ако потребител съобщи, че "данните бяха грешни в 14:32", можете да направите replay на точния request.
- **Проследяване в Dashboard**: същото ID се показва в [Activity feed](https://foura.ai/docs/dashboard/activity-log) за ключовете, които управлявате, така че можете да отворите съответния ред и да прегледате записаните request и response.

### Пример: логване от ваша страна

```python
import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    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},
    )
    request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()
```

```javascript
async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}
```

## X-FourA-Credits

`X-FourA-Credits` отчита цената в кредити за заявката, която току-що направихте. Това е брояч, а не фактура: заглавката отразява изразходваното за извършената работа независимо от крайния резултат. Счетоводният слой на таблото отчита към вашия план само таксуемите резултати (вижте [Request Outcomes](https://foura.ai/docs/api/outcomes) за това кои резултати са таксуеми).

### Справка за цените

| Engine | Base | With `unblocker` |
|--------|------|------------------|
| Single | 1 | 2 |
| Proxy | 2 | 4 |
| Browser | 5 | 10 (when a defense was solved) |

`/api/auto/` е една заявка във вашето табло с цена в кредити, която представлява сумата от вътрешно направените подзаявки (едно повторно изпълнение към загрят таргет може да завърши на 2; студено разрешаване на труден сайт може да изразходи много повече). Стойността на `X-FourA-Credits` в auto отговора съответства на `meta.credits` в тялото и отчита пълната цена по стълбицата.

### Защо и заглавка, и поле в тялото?

Заглавката е удобна: можете да я прочетете преди парсване на тялото, да я запишете в лога до реда на заявката или да я сумирате за множество извиквания без парсване на JSON. При Auto полето `meta.credits` в тялото съдържа същото число. Телата на Single, Proxy и Browser не го съдържат, така че при тези отговори заглавката е единственото място за прочитането му. Редът [Activity](https://foura.ai/docs/dashboard/activity-log) за всяко извикване също го показва.

## X-FourA-Limit

`X-FourA-Limit` се появява само когато някой от лимитите на вашия план е отказал заявката. Споделените rate limits на платформата никога не го задават, така че заглавката е най-бързият начин да разграничите "планът ми спря това" от "FourA е зает", без да парсвате тялото.

```
HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json
```

Две от седемте стойности се връщат с 403 вместо 429: `plan_limit_feature` (endpoint адресът или параметърът `exitCountries` не е включен във вашия план) и `plan_limit_premium` (`exitClass: premium` не е включен във вашия план). Нито една от двете не задава `Retry-After`, тъй като изчакването няма да промени отговора.

```python
STOP_ON = {
    "plan_limit_feature", "plan_limit_premium",
    "plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}

resp = requests.post(url, headers=headers, json=payload)

limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
    stop_the_run(limit)                # hours or days away, not seconds
elif limit:
    time.sleep(int(resp.headers.get("Retry-After", 1)))
```

Седемте стойности и съответните полета в body са описани в [Rate Limits](https://foura.ai/docs/api/rate-limits).

## X-FourA-Exit-Class

`X-FourA-Exit-Class` указва класа на изхода, доставил body: `premium` при премиум изход, `standard` при стандартния пул. Появява се при `POST /api/proxy/` или `POST /api/auto/` response, доставил страница, когато в request е посочен `exitClass`, като body носи същата стойност (`exitClass` при Proxy, `meta.exitClass` при Auto), както и при Single или Browser response, когато фиксираният `proxy` е бил премиум изход, където в body няма поле за това. При неуспешно извикване на Proxy или Auto не се връща нищо, затова то не съдържа нито header, нито полето.

```
HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

Трафикът през premium изход се отчита както към вашия premium трафик, така и към общия ви bandwidth. Той се измерва в мрежата и включва premium опити, които не са върнали вашата страница, така че заявка, отговорена с `standard`, все още може да е използвала част от premium трафика при опит, неуспял преди отговора от стандартния пул. Този header посочва класа, който е доставил отговора, а не дали е използван premium трафик: маркировката **premium** на ред в [Activity](https://foura.ai/docs/dashboard/activity-log) и страницата [Usage & Limits](https://foura.ai/docs/dashboard/quota) показват какво е било отчетено. Какво прави `exitClass` и кога се използва premium изход: [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

## X-FourA-Browser-Used-Today и X-FourA-Browser-Limit-Per-Day

Тези два header-а съдържат вашия дневен лимит за браузър в самия отговор, същите стойности, които страницата [Usage & Limits](https://foura.ai/docs/dashboard/quota) показва, за да можете да го проследявате без polling към таблото за управление.

```
HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

Броячът се нулира в полунощ UTC и обхваща всеки ключ към вашия план, а не само този, извършил това извикване. Заявка, отхвърлена поради лимитите на плана, не съдържа нито един от двата хедъра: вместо това нейното тяло съдържа `used_today` и `limit_per_day`, вижте [Rate Limits](https://foura.ai/docs/api/rate-limits).

При `POST /api/browser/` броят включва заявката, която четете в момента. При `POST /api/auto/` това е най-високата стойност, подадена на стълбицата по време на изпълнението, така че може да изостава спрямо дневната стойност заради други ваши заявки, които все още се изпълняват. Auto отговор, при който не е изпратена заявка, като например 120-секундната пауза след повторни неуспешни опити към даден сайт, не съдържа нито един от двата хедъра. Стойността, която едно Auto извикване е отнело от брояча, се намира в `meta.browserRequests`: вижте [Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Поведение на кеша

API не задава `Cache-Control`. Даден отговор може да съдържа слаб `ETag`, изчислен от неговото тяло, но нищо не се кешира: всяко извикване достига до бекенда. Ако се нуждаете от кеширане, добавете го от ваша страна.

## Хедъри на целевия отговор

Хедърите, върнати от целевия сайт, не присъстват в FourA API отговора. Те се връщат вътре в JSON обвивката като полето `headers`. За Single и Proxy крайните точки това е масив от обекти с хедъри за всяка междинна стъпка (по един запис за всяка стъпка на пренасочване). За Browser крайната точка това е плосък обект с хедърите на окончателния отговор.

```json
{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}
```

Ако се нуждаете от конкретен целеви header, прочетете го от полето `headers` на обвивката, а не от самия HTTP response на API извикването.

## Свързани

- [API Endpoints](https://foura.ai/docs/api/endpoints): Структури на request и response обвивките
- [API Errors](https://foura.ai/docs/api/errors): Как са структурирани отговорите за грешка
- [Request Outcomes](https://foura.ai/docs/api/outcomes): Кои резултати са платими
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): История за всяка заявка по request ID
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Какво означава всяка стойност на `X-FourA-Limit`
