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를 참조하십시오.
Content-Type 모든 응답 엔벨로프의 경우 항상 application/json입니다. 대상의 content-type은 엔벨로프의 headers 필드 내에 반환됩니다.

X-FourA-Request-Id

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

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 피드에 동일한 ID가 표시되므로 일치하는 행을 열어 캡처된 request 및 response를 검사할 수 있습니다.

예시: 클라이언트 측 로그

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()
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 참조).

비용 참조

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 행에도 표시됩니다.

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를 설정하지 않습니다.

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에 명시되어 있습니다.

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 행의 premium 표시와 Usage & Limits 페이지에서 확인할 수 있습니다. exitClass의 역할과 프리미엄 출구가 사용되는 시점은 exitClass를 참고하십시오.

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

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

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를 참고하십시오.

POST /api/browser/의 카운트에는 현재 읽고 있는 요청이 포함됩니다. POST /api/auto/의 경우 래더 실행 중에 부여된 가장 높은 카운트이므로, 아직 실행 중인 다른 요청들로 인해 당일 수치보다 지연될 수 있습니다. 사이트의 반복된 실패 후 발생하는 120초 일시 중지와 같이 요청을 보내지 않은 Auto 응답에는 두 헤더가 모두 포함되지 않습니다. 단일 Auto 호출이 카운트에서 차감한 수치는 meta.browserRequests에 기록됩니다. Smart Fetch를 참고하십시오.

캐시 동작

API는 Cache-Control을 설정하지 않습니다. 응답 본문에서 계산된 약한 ETag이 포함될 수 있지만 아무것도 캐시되지 않습니다. 모든 호출은 백엔드로 전달됩니다. 캐싱이 필요하다면 클라이언트 측에 직접 구현하십시오.

대상 응답 헤더

대상 사이트가 반환한 헤더는 FourA API 응답에 포함되지 않습니다. 이 헤더들은 JSON 엔벨로프 내부의 headers 필드로 반환됩니다. Single 및 Proxy 엔드포인트의 경우 홉별 헤더 객체 배열(리디렉션 단계당 하나의 항목)로 제공됩니다. Browser 엔드포인트의 경우 최종 응답 헤더의 플랫 객체로 제공됩니다.

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

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

최근 업데이트: 2026년 11월 5일