Response Headers

FourA API의 모든 response에는 소수의 커스텀 header 세트가 포함됩니다. 이 header들은 추적, 기술 지원, 요금 정산 및 사후 분석에 유용합니다.

FourA가 설정하는 Headers

X-FourA-Request-Id

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

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 feed에 동일한 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는 방금 실행한 호출의 크레딧 비용을 보고합니다. 이는 청구서가 아닌 계측기 역할을 하며, 결과와 관계없이 작업에 소모된 비용을 반영합니다. 대시보드의 청구 레이어는 과금 가능한 결과만 플랜 사용량으로 계산합니다(과금 대상 결과는 Request Outcomes 참조).

비용 기준

/api/auto/는 대시보드에서 1건의 요청으로 표시되며, 내부적으로 발생한 하위 호출의 합계가 크레딧 비용이 됩니다(웜 타깃에 대한 단일 재생은 2로 완료될 수 있으며, 난도가 높은 사이트의 콜드 해결은 훨씬 더 많이 소모될 수 있습니다). auto 응답의 X-FourA-Credits 값은 본문의 meta.credits과 동일하며 전체 래더 비용을 추적합니다.

헤더와 본문 필드가 모두 제공되는 이유

헤더는 편리합니다. 본문을 파싱하기 전에 읽을 수 있고, 요청 라인 바로 옆에 로깅할 수 있으며, JSON 파싱 없이도 여러 호출의 비용을 합산할 수 있습니다. 본문의 meta.credits(Auto) 또는 엔진별 메타데이터(Single, Proxy, Browser 대시보드)에도 동일한 수치가 포함되어 응답 엔벨로프 내부에서 확인할 수 있습니다.

X-FourA-Limit

X-FourA-Limit는 플랜의 제한으로 인해 호출이 거부되었을 때만 표시됩니다. 플랫폼의 공유 rate limit에 걸린 경우에는 설정되지 않으므로, 본문을 파싱하지 않고도 "내 플랜 제한에 도달함"과 "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가지 값과 각 값에 포함되는 body 필드는 Rate Limits에 나와 있습니다.

X-FourA-Exit-Class

X-FourA-Exit-Class는 body를 전달한 exit의 클래스를 지정합니다. 프리미엄 exit가 전달한 경우 premium, 표준 풀이 전달한 경우 standard입니다. request에서 exitClass을 지정하여 페이지를 전달한 POST /api/proxy/ response에 표시되며 body에도 동일한 값이 포함됩니다. 또한 고정한 proxy가 프리미엄 exit일 때 Single 또는 Browser response에 표시되지만 body에는 해당 필드가 없습니다. 실패한 Proxy 호출은 아무것도 제공하지 않으므로 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.

Cache Behavior

API는 응답에 Cache-Control 또는 ETag을(를) 설정하지 않습니다. 모든 호출은 백엔드에 직접 도달합니다. 캐싱이 필요한 경우 클라이언트 측에 직접 구현하십시오.

Target Response Headers

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

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

특정 타깃 header가 필요한 경우, API 호출 자체의 HTTP response가 아닌 envelope의 headers 필드에서 읽으십시오.

Related

• API Endpoints: Request 및 response envelope 구조
• API Errors: 오류 response 구조
• Request Outcomes: 과금 대상 outcome 안내
• Activity Log: request ID 기준 request별 기록
• Rate Limits: 각 X-FourA-Limit 값의 의미