# レスポンスヘッダー

> URL: https://foura.ai/ja/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

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](https://foura.ai/docs/api/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は認証が失敗した場合でも設定されるため、設定ミスによる呼び出しの関連付けも可能です。

```bash
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を再現できます。
- **ダッシュボードでの追跡**: 管理対象キーの[アクティビティフィード](https://foura.ai/docs/dashboard/activity-log)にも同じIDが表示されるため、対応する行を開いてキャプチャされたrequestおよびresponseを確認できます。

### 例: 自社側でのログ記録

```python
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()
```

```javascript
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](https://foura.ai/docs/api/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](https://foura.ai/docs/dashboard/activity-log) 行にも表示されます。

## 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`を設定しません。

```python
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](https://foura.ai/docs/api/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](https://foura.ai/docs/dashboard/activity-log)行の**premium**マークと[Usage & Limits](https://foura.ai/docs/dashboard/quota)ページに、カウントされた内容が表示されます。`exitClass`の動作およびpremium exitが使用されるタイミングについては、[exitClass](https://foura.ai/docs/api/endpoints#exitclass)を参照してください。

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

これら2つのheaderは、[Usage & Limits](https://foura.ai/docs/dashboard/quota)ページに表示される数値と同じ、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](https://foura.ai/docs/api/rate-limits)を参照してください。

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

## キャッシュの動作

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

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

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

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

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

## 関連情報

- [APIエンドポイント](https://foura.ai/docs/api/endpoints): リクエストおよびレスポンスのエンベロープ構造
- [APIエラー](https://foura.ai/docs/api/errors): エラーレスポンスの構造
- [リクエスト結果](https://foura.ai/docs/api/outcomes): 課金対象となる結果
- [アクティビティログ](https://foura.ai/docs/dashboard/activity-log): リクエストIDをキーとするリクエストごとの履歴
- [レート制限](https://foura.ai/docs/api/rate-limits): 各`X-FourA-Limit`値の意味
