Response Headers

FourA API의 모든 response에는 소규모의 사용자 지정 header 세트가 포함됩니다. 추적, 지원, 결제 조정 및 사후 분석에 유용합니다.

FourA가 설정하는 Headers

Header	Set on	Description
`X-Foura-Request-Id`	오류 및 401을 포함한 모든 `/api/*` response	이 request를 식별하는 UUID입니다. 사용자 측에서 로깅하세요.
`X-FourA-Credits`	백엔드에 도달한 모든 `/api/*` response	이 호출에 사용된 크레딧입니다. 성공 및 실패 시 모두 반환됩니다 (작업은 어느 쪽이든 수행됨).
`Content-Type`	모든 response	envelope의 경우 항상 `application/json`입니다. 대상의 content-type은 envelope의 `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
...

사용 시기

Support tickets: request ID를 포함하면 기록에서 정확한 호출을 찾을 수 있습니다.
Your own logs: 애플리케이션 로그 라인 옆에 저장하세요. 고객 불만에 "14:32에 데이터가 잘못되었습니다"라고 명시되어 있는 경우 정확한 request를 다시 재생할 수 있습니다.
Dashboard tracing: 관리하는 키에 대해 동일한 ID가 Activity feed에 표시되므로, 일치하는 행을 열고 캡처된 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	5	10
Browser	15	30 (방어가 해결된 경우)

/api/auto/은 별도의 청구 가능한 행을 추가하지 않습니다. 이 크레딧 비용은 내부적으로 수행된 하위 호출의 합계입니다(따뜻한 대상에서 단일 재생은 2로 완료될 수 있으며, 어려운 사이트에서 콜드 솔브는 훨씬 더 많은 비용을 소비할 수 있습니다). auto response의 X-FourA-Credits 값은 본문의 meta.credits과 같으며 전체 래더 비용을 추적합니다.

왜 header와 body 필드 모두에 있나요?

header는 편리합니다. 본문을 파싱하기 전에 읽거나, request 줄 옆에 로깅하거나, JSON 파싱 없이 많은 호출에 걸쳐 합산할 수 있습니다. 본문의 meta.credits(Auto) 또는 엔진별 메타데이터(Single, Proxy, Browser 대시보드)는 동일한 숫자를 유지하지만 response envelope 내부에서 읽을 수 있습니다.

캐시 동작

API는 response에 Cache-Control 또는 ETag을 설정하지 않습니다. 모든 호출은 백엔드에 도달합니다. 캐싱이 필요한 경우 사용자 측에 추가하세요.

대상 Response Headers

대상 사이트가 반환한 headers는 FourA API response에 없습니다. JSON envelope 내부에서 headers 필드로 반환됩니다. Single 및 Proxy endpoints의 경우, 이는 홉별 header 객체의 배열(리디렉션 단계당 하나의 항목)입니다. Browser endpoint의 경우, 최종 response headers의 플랫 객체입니다.

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

특정 대상 header가 필요한 경우, API 호출 자체의 HTTP response에서 읽지 말고 envelope의 headers 필드에서 읽으세요.