レスポンスヘッダー

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

FourAが設定するHeader

Header 設定対象 説明
X-FourA-Request-Id IDが割り当てられる前に拒否される、FourAがまったく読み取れないbody (400 Invalid JSON in request body、413) を除く、エラーおよび401を含むすべての/api/* response このrequestを識別するUUID。クライアント側でログに記録してください。
X-FourA-Credits バックエンドに到達したすべての/api/* response この呼び出しで消費されたクレジット。成功時および失敗時の両方で返されます (どちらの場合も処理が実行されたため)。
X-FourA-Limit プラン制限のいずれかによって発生したすべての403または429 呼び出しを拒否した制限: plan_limit_、その後にfeature、premium、concurrency、rate、browser_daily、credits、またはbandwidthが続きます。
Retry-After 待機によって解消されるプラン制限の429 (並行性、レート、クレジット、帯域幅) および503 API key check temporarily unavailable 待機する秒数 (整数)。プラン制限のbody内のretry_after_secondsおよび503のretryAfterと一致します。
X-FourA-Exit-Class exitClassを指定してページを返したすべての/api/proxy/または/api/auto/の呼び出し、およびプレミアムexit経由で配信されたすべてのSingleまたはBrowserの呼び出し premiumまたはstandard: bodyを配信したexitのクラス。失敗したProxy呼び出しは何も配信せず、このheaderも含まれません。
X-FourA-Browser-Used-Today プラン制限によって拒否されなかったすべてのPOST /api/browser/応答、および拒否されなかったrequestをラダーが送信したすべてのPOST /api/auto/応答 本日アカウントでカウントされたBrowser request数: 以下を参照してください。
X-FourA-Browser-Limit-Per-Day プランに1日の上限が設定されている場合の同じ応答 プランで1日に許可されているBrowser request数。
X-FourA-Check-Page HTTP 200 bodyがFourAの認識するボットチェックまたは拒否ページであるSingle、Proxy Finder、Browserのresponse ページ名 (例: amazon-captcha)。このようなrequestは課金されません: Request Outcomesを参照してください。
Content-Type すべてのresponse エンベロープ用として常にapplication/json。ターゲットのcontent-typeはエンベロープの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を再現できます。
  • ダッシュボードでの追跡: 管理対象キーのアクティビティフィードにも同じ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 を参照してください)。

コストリファレンス

Engine Base With unblocker
Single 1 2
Proxy 2 4
Browser 5 10 (防御を解決した場合)

/api/auto/ はダッシュボード上では1リクエストとして扱われ、クレジットコストは内部で実行されたサブコールの合計になります (ウォームなターゲットに対する単一のリプレイでは2で完了することがありますが、難度の高いサイトに対するコールドな解決でははるかに多くを消費する可能性があります)。auto レスポンスの X-FourA-Credits の値はボディ内の meta.credits と一致し、ラダー全体のコストを追跡します。

なぜヘッダーとボディフィールドの両方があるのか?

ヘッダーは利便性に優れています。ボディをパースする前に読み取ったり、リクエスト行の横に記録したり、JSON をパースすることなく多数の呼び出しにわたって合算したりできます。Auto では、ボディの meta.credits にも同じ数値が保持されます。Single、Proxy、Browser のボディにはこのフィールドが含まれないため、これらのレスポンスではヘッダーのみが値を確認できる場所となります。各呼び出しの Activity 行にも表示されます。

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を配信したエグジットのクラスを指定します。プレミアムエグジットが配信した場合はpremium、標準プールが配信した場合はstandardとなります。requestでexitClassを指定してページを配信したPOST /api/proxy/またはPOST /api/auto/ responseに表示され、bodyにも同じ値が含まれます(ProxyではexitClass、Autoではmeta.exitClass)。また、固定したproxyがプレミアムエグジットだった場合のSingleまたはBrowser responseにも表示されますが、この場合bodyに対応するフィールドはありません。失敗した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

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

X-FourA-Browser-Used-TodayおよびX-FourA-Browser-Limit-Per-Day

これら2つのheaderは、Usage & Limitsページに表示される数値と同じ、1日あたりのブラウザ許容量を応答自体に含めて返します。これにより、ダッシュボードをポーリングすることなく上限を追跡できます。

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午前0時にリセットされ、この呼び出しを実行したキーだけでなく、プラン上のすべてのキーを対象とします。プランの制限により拒否されたリクエストにはどちらのヘッダーも含まれません。代わりにレスポンスボディにused_todayおよびlimit_per_dayが含まれます。詳細はRate Limitsを参照してください。

POST /api/browser/では、カウントに現在読み取り中のリクエストが含まれます。POST /api/auto/では、実行中にラダーに渡された最大カウントとなるため、並行して実行中の他のリクエストによってその日の合計カウントより遅れる場合があります。サイトで連続して失敗した後の120秒の一時停止など、リクエストを送信しなかったAutoのレスポンスにはどちらのヘッダーも含まれません。1回のAuto呼び出しによってカウントから消費された値はmeta.browserRequestsに含まれます。詳細はSmart Fetchを参照してください。

キャッシュの動作

APIはCache-Controlを設定しません。レスポンスにはボディから算出された弱いETagが含まれる場合がありますが、何もキャッシュされず、すべての呼び出しがバックエンドに到達します。キャッシュが必要な場合は、クライアント側で実装してください。

ターゲットレスポンスヘッダー

ターゲットサイトから返されたヘッダーは、FourA APIレスポンスには含まれません。それらはJSONエンベロープ内のheadersフィールドとして返されます。SingleおよびProxyエンドポイントの場合、これはホップごとのヘッダーオブジェクトの配列(リダイレクトステップごとに1エントリ)になります。Browserエンドポイントの場合、最終レスポンスヘッダーのフラットなオブジェクトになります。

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

特定のターゲットヘッダーが必要な場合は、APIコール自体のHTTPレスポンスからではなく、エンベロープのheadersフィールドから読み取ってください。

最終更新日: 2026年11月5日