# 응답 헤더

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

FourA API의 모든 응답에는 소수의 커스텀 헤더가 포함됩니다. 이 헤더는 추적, 지원, 결제 대사, 사후 분석에 유용합니다.

## FourA가 설정하는 헤더

| Header | 설정 대상 | 설명 |
|--------|--------|-------------|
| `X-FourA-Request-Id` | ID가 할당되기 전에 거부되어 FourA가 본문을 전혀 읽을 수 없는 경우(`400 Invalid JSON in request body`, `413`)를 제외한, 오류 및 401을 포함한 모든 `/api/*` 응답 | 이 request를 식별하는 UUID입니다. 클라이언트 측에 기록하십시오. |
| `X-FourA-Credits` | 백엔드에 도달한 모든 `/api/*` 응답 | 이 호출에 사용된 크레딧입니다. 성공 및 실패 시 모두 반환됩니다(작업은 어느 쪽이든 수행되었기 때문입니다). |
| `X-FourA-Limit` | 플랜 한도 중 하나로 인해 발생한 모든 `403` 또는 `429` | 호출을 거부한 한도 항목: `plan_limit_` 뒤에 `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits` 또는 `bandwidth`가 이어집니다. |
| `Retry-After` | 대기를 통해 해결되는 플랜 한도 `429`(동시성, rate, 크레딧, 대역폭) 및 503 `API key check temporarily unavailable` | 정수 형태의 대기 시간(초)입니다. 플랜 한도 본문의 `retry_after_seconds` 및 503의 `retryAfter`와 일치합니다. |
| `X-FourA-Exit-Class` | `exitClass`를 지정하고 페이지를 전달한 모든 `/api/proxy/` 또는 `/api/auto/` 호출, 그리고 프리미엄 출구를 통해 제공된 모든 Single 또는 Browser 호출 | `premium` 또는 `standard`: 본문을 전달한 출구 클래스입니다. 실패한 Proxy 호출은 아무것도 전달하지 않으며 헤더도 포함하지 않습니다. |
| `X-FourA-Browser-Used-Today` | 플랜 한도로 인해 거부되지 않은 모든 `POST /api/browser/` 응답 및 사다리가 거부되지 않은 request를 전송한 모든 `POST /api/auto/` 응답 | 오늘 계정에 집계된 Browser request 수입니다. 아래를 참조하십시오. |
| `X-FourA-Browser-Limit-Per-Day` | 플랜에 일일 제한 수가 설정된 경우의 동일한 응답 | 플랜에서 일일 허용하는 Browser request 수입니다. |
| `X-FourA-Check-Page` | HTTP 200 본문이 FourA에서 인식하는 봇 감지 또는 거부 페이지인 Single, Proxy Finder 및 Browser 응답 | `amazon-captcha`와 같은 페이지 이름입니다. 이러한 request는 비용이 청구되지 않습니다. [Request Outcomes](https://foura.ai/docs/api/outcomes)를 참조하십시오. |
| `Content-Type` | 모든 응답 | 엔벨로프의 경우 항상 `application/json`입니다. 대상의 content-type은 엔벨로프의 `headers` 필드 내에 반환됩니다. |

## X-FourA-Request-Id

`POST /api/auto/`, `POST /api/single/`, `POST /api/proxy/` 또는 `POST /api/browser/`에 대한 각 호출에는 UUID 태그가 지정됩니다. 인증에 실패하더라도 헤더가 설정되므로 잘못 구성된 호출도 연계하여 추적할 수 있습니다.

```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
...
```

### 사용 시점

- **지원 티켓**: request ID를 포함하면 기록에서 해당 호출을 정확히 찾을 수 있습니다.
- **자체 로그**: 애플리케이션 로그 라인 옆에 함께 저장하십시오. 고객이 "14:32에 데이터가 잘못되었습니다"라고 문의하는 경우 해당 request를 그대로 재생할 수 있습니다.
- **대시보드 추적**: 관리하는 키의 [Activity 피드](https://foura.ai/docs/dashboard/activity-log)에 동일한 ID가 표시되므로 일치하는 행을 열어 캡처된 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`는 방금 수행한 호출의 크레딧 비용을 보고합니다. 이는 청구서가 아닌 계측기입니다. 결과와 관계없이 작업에 소비된 비용을 header에 반영합니다. 대시보드의 청구 계층은 플랜에 대해 청구 가능한 결과만 계산합니다(청구 가능한 결과에 대한 자세한 내용은 [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/`는 대시보드에서 1개의 request로 표시되며, 크레딧 비용은 내부적으로 수행된 하위 호출의 합계입니다(warm 타깃에 대한 단일 replay는 2로 끝날 수 있고, 어려운 사이트에 대한 cold solve는 훨씬 더 많이 소비될 수 있습니다). auto response의 `X-FourA-Credits` 값은 본문의 `meta.credits`와 동일하며 전체 ladder 비용을 추적합니다.

### header와 body 필드가 모두 존재하는 이유

header는 편리합니다. body를 파싱하기 전에 읽거나, request 라인 옆에 로깅하거나, JSON 파싱 없이 여러 호출에 걸쳐 합산할 수 있습니다. Auto의 경우 본문의 `meta.credits`에 동일한 숫자가 포함됩니다. Single, Proxy, Browser 본문에는 이 값이 포함되지 않으므로, 해당 response에서는 header가 유일하게 확인할 수 있는 위치입니다. 각 호출의 [Activity](https://foura.ai/docs/dashboard/activity-log) 행에도 표시됩니다.

## X-FourA-Limit

`X-FourA-Limit`는 플랜 한도 중 하나로 인해 호출이 거부된 경우에만 나타납니다. 플랫폼의 공유 rate limit는 이를 설정하지 않으므로, 이 header는 body를 파싱하지 않고도 "내 플랜에서 차단함"과 "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
```

7개 값 중 2개는 429 대신 403과 함께 반환됩니다. `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)))
```

7가지 값과 각 값에 동반되는 본문 필드는 [Rate Limits](https://foura.ai/docs/api/rate-limits)에 명시되어 있습니다.

## X-FourA-Exit-Class

`X-FourA-Exit-Class` 헤더는 본문을 전달한 exit 클래스를 지정합니다. 프리미엄 exit이 전달한 경우 `premium`, 표준 풀이 전달한 경우 `standard`입니다. request가 `exitClass`를 지정한 상태에서 페이지를 전달한 `POST /api/proxy/` 또는 `POST /api/auto/` response에 표시되며, 이때 본문에도 동일한 값이 포함됩니다(Proxy에서는 `exitClass`, Auto에서는 `meta.exitClass`). 또한 고정한 `proxy`가 프리미엄 exit인 Single 또는 Browser response에도 표시되며, 이 경우 본문에는 해당 필드가 없습니다. 실패한 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
```

프리미엄 출구를 통과하는 트래픽은 총 대역폭뿐만 아니라 프리미엄 트래픽에도 반영됩니다. 네트워크 상에서 측정되며 페이지를 반환하지 못한 프리미엄 시도도 포함되므로, `standard` 응답을 받은 요청이라도 표준 풀이 응답하기 전에 실패한 시도에서 프리미엄 트래픽을 일부 소모했을 수 있습니다. 이 헤더는 프리미엄 트래픽 사용 여부가 아니라 실제로 전달한 클래스를 나타냅니다. 집계된 내역은 [Activity](https://foura.ai/docs/dashboard/activity-log) 행의 **premium** 표시와 [Usage & Limits](https://foura.ai/docs/dashboard/quota) 페이지에서 확인할 수 있습니다. `exitClass`의 역할과 프리미엄 출구가 사용되는 시점은 [exitClass](https://foura.ai/docs/api/endpoints#exitclass)를 참고하십시오.

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

이 두 헤더는 대시보드를 반복 조회할 필요 없이 확인할 수 있도록 [Usage & Limits](https://foura.ai/docs/dashboard/quota) 페이지와 동일한 일일 브라우저 허용량을 응답 자체에 담아 제공합니다.

```
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/`의 경우 래더 실행 중에 부여된 가장 높은 카운트이므로, 아직 실행 중인 다른 요청들로 인해 당일 수치보다 지연될 수 있습니다. 사이트의 반복된 실패 후 발생하는 120초 일시 중지와 같이 요청을 보내지 않은 Auto 응답에는 두 헤더가 모두 포함되지 않습니다. 단일 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
}
```

특정 대상 헤더가 필요한 경우 API 호출 자체의 HTTP 응답이 아닌 envelope의 `headers` 필드에서 읽으십시오.

## 관련 항목

- [API Endpoints](https://foura.ai/docs/api/endpoints): Request 및 response envelope 구조
- [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` 값의 의미
