Response Headers

FourA APIからのすべてのresponseには、少数のカスタムheaderが含まれています。これらはトレーシング、サポート、請求の照合、および事後分析に役立ちます。

Headers FourA Sets

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を正確に再現できます。
• ダッシュボードでの追跡: 管理対象キーのアクティビティフィードにも同じ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件の request としてカウントされ、そのクレジットコストは内部で実行されたサブコールの合計となります（ウォームなターゲットに対する単一のリプレイなら2で完了することもありますが、難度の高いサイトでのコールド解決ではより多く消費される場合があります）。Auto レスポンスの X-FourA-Credits の値は body 内の meta.credits と一致し、ラダー全体のコストを追跡します。

ヘッダーと body フィールドの両方がある理由

ヘッダーは利便性に優れています。body をパースする前に読み取ったり、リクエストラインの横にログ出力したり、JSON をパースせずに多数の呼び出しにわたって合算したりできます。body の meta.credits（Auto）またはエンジンごとのメタデータ（Single、Proxy、Browser ダッシュボード）にも同じ数値が含まれており、レスポンスエンベロープ内で読み取ることができます。

X-FourA-Limit

X-FourA-Limit は、プランの上限によって呼び出しが拒否された場合にのみ表示されます。プラットフォームの共有 rate limit によって設定されることはないため、このヘッダーを使用すると、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つの値とそれぞれに含まれるbodyフィールドは、Rate Limitsに記載されています。

X-FourA-Exit-Class

X-FourA-Exit-Classはbodyを配信したexitのクラスを示します。プレミアムexitが配信した場合はpremium、標準プールが配信した場合はstandardとなります。これは、リクエストがexitClassを指定し、ページを配信したPOST /api/proxy/レスポンス（bodyにも同じ値が含まれます）に表示されます。また、ピン留めしたproxyがプレミアムexitであった場合のSingleまたはBrowserレスポンス（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

プレミアム exit 経由のトラフィックは、合計帯域幅だけでなくプレミアムトラフィックとしてもカウントされます。これはネットワーク上で計測され、ページを返せなかったプレミアム試行も含まれます。そのため、standard で応答された request であっても、標準プールが応答する前に失敗した試行でプレミアムトラフィックが消費されている可能性があります。この header は配信したクラスを示すものであり、プレミアムトラフィックが使用されたかどうかを示すものではありません。Activity 行の premium マークおよび Usage & Limits ページに、カウントされた内容が表示されます。exitClass の動作とプレミアム exit が使用されるタイミング: exitClass。

Cache Behavior

API は response に Cache-Control や ETag を設定しません。すべての呼び出しがバックエンドに到達します。キャッシュが必要な場合は、クライアント側で実装してください。

Target Response Headers

ターゲットサイトが返した header は、FourA API の response には含まれません。これらは JSON エンベロープ内の headers フィールドとして返されます。Single および Proxy endpoint の場合、これはホップごとの header オブジェクトの配列（リダイレクトステップごとに1つのエントリ）になります。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からではなく、エンベロープのheadersフィールドから読み取ってください。

関連情報

• API Endpoints: requestおよびresponseエンベロープの構造
• API Errors: エラーresponseの構成
• Request Outcomes: 課金対象となる結果
• Activity Log: request IDをキーとするrequestごとの履歴
• Rate Limits: 各X-FourA-Limit値の意味