# よくある問題

> URL: https://foura.ai/ja/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

FourA APIの使用時によくある問題の解決策です。

## 空または不完全なコンテンツ

**症状:** APIは200ステータスを返しますが、`data`フィールドが空か、期待されるコンテンツが含まれていません。

**原因:** 対象ページが初回のページ読み込み後にJavaScriptを使用してコンテンツをレンダリングしています。

**解決策:** single endpointからbrowser endpointに切り替えてください。`checkText`を使用してコンテンツが読み込まれたことを確認します。

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

注意: browser endpointはコンテンツを`body`フィールド（`data`ではなく）で返します。

## 403 Forbiddenまたは検証ページ

**症状:** APIが検証ページまたはアクセス拒否ページを含むHTMLを返します。

**原因:** 対象サイトがリクエストを自動化されたものとして検知し、ブロックしました。

**解決策:** 自動IPローテーションを利用するにはproxy endpointを使用してください:

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'
```

問題が解決しない場合は、`maxTries` を増やして proxy ローテーションの試行回数を増やしてください。

ターゲットが返した 403 は、body 内に `status: 403` を含む HTTP 200 として到達します。`X-FourA-Limit` ヘッダーを伴うコール自体の 403 は別の問題です。[プランに含まれていない 403](#403-not-in-your-plan) を参照してください。

## タイムアウトエラー

**症状:** リクエストがタイムアウトエラーで失敗します。

**原因:** ターゲットページの読み込みに、設定されたタイムアウト以上の時間がかかっています。

**解決策:** `timeout_ms` を増やしてください (デフォルトは single で 15秒、browser で 30秒、proxy で 45秒):

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'
```

ブラウザリクエストの場合、`checkText` の値が実際にページ上に表示されていることも確認してください。タイポがあると `checkText:<your text> not found` で呼び出しが失敗します。

## 403 ご利用のプランに含まれていません

**症状:** APIが `X-FourA-Limit` ヘッダー、および `plan_limit_feature` または `plan_limit_premium` の `reason` とともに 403 を返します。

```json
{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

**原因:** ご利用中のプランには、呼び出した endpoint または送信したパラメータが含まれていません。`plan_limit_feature` は対象外の endpoint を示し、`exitCountries`、`exitState`、`exitCity`、`exitAsn`、または `exitOs` は地域ターゲティングなしのプランに適用されます。`plan_limit_premium` はプレミアム出口なしの `exitClass: premium`、およびプレミアムトラフィックを使い果たした後に [exit location](https://foura.ai/docs/api/endpoints#exit-location) を指定した Proxy request を示します。ターゲットへの接続は行われず、クレジット等も消費されていません。

**解決策:** パラメータを削除するか、プランに含まれる endpoint を呼び出すか、アップグレードしてください。[Usage & Limits](https://foura.ai/docs/dashboard/quota) の **Limits & Features** タブにプランに含まれる内容が一覧表示されています。変更を加えずに再試行しないでください。待機しても結果は変わらないため、`Retry-After` は設定されません。

## 429 リクエスト過多

**症状:** API が 429 を返します。

**原因:** 2つのチェックのいずれかによって呼び出しが拒否されました。どちらであるかはレスポンスで判別できます。`X-FourA-Limit` header が含まれている場合、該当 endpoint での同時リクエスト数や1分あたりのリクエスト数、1日の Browser リクエスト数、または請求期間のクレジットや帯域幅など、プランの上限のいずれかに達しています。該当 header がない場合は、そのサービスに対するプラットフォーム共有の1分あたりの割り当てが上限に達しており、これはユーザー自身ではなく FourA のトラフィックに起因します。

**解決策:** まず `X-FourA-Limit` を確認してください。制限解除まで数秒であれば待機し、そうでなければリクエストを停止します。待機によって解除されるプランの上限については、`Retry-After` header および `retry_after_seconds` に待機秒数が示されます。プラットフォーム共有の上限の場合は `retryAfter` に示されます。

```python
import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)
```

ヘッダーに`plan_limit_concurrency`または`plan_limit_rate`と示されている場合、対処法はリトライを繰り返すことではなく、開いたままにする接続数と1分あたりに開始する呼び出し数を制限することです。拒否されたバッチをすぐに再送信すると、バッチ全体が再度拒否されます。拒否された呼び出しは1分あたりの制限にはカウントされませんが、その制限の2倍以上のペースで送信され続けると、拒否状態からクールダウンに移行します。429の本文に`cooldown: true`が含まれ、30秒間の一時停止（`retry_after_seconds: 30`）が要求されます。具体的なパターンは[リクエストを並行して実行](https://foura.ai/docs/how-to/run-requests-in-parallel)に記載されており、[ダッシュボード](https://foura.ai/dashboard)の**使用状況と制限**で、現在のカウンターと上限を並べて確認できます。

## 503 サービス利用不可

**症状:** APIが503ステータスを返します。

**原因:** これは3つのケースで発生します:

1. **サービスの処理能力の上限に達している。** FourAが、ユーザー固有のトラフィックだけでなく全体トラフィックを対象として、対象エンジンで同時に実行可能な最大数のリクエストをすでに処理しています。`error`フィールドに`Service at capacity`が設定されます。通常は数秒で解消されます。
2. **サービスが一時的に無効化されている。** メンテナンス期間中です。`error`フィールドに`Service disabled`が設定されます。
3. **一時的にAPIキーを確認できない。** `error`フィールドに`API key check temporarily unavailable`が設定され、`Retry-After: 5`が返されます。キー自体に問題はありません。

3つのケースすべてで、レスポンスに`retryAfter`フィールドが含まれます。いずれもプランの上限によるものではありません。契約プランの上限に達した場合は、503ではなく必ず403または429に`X-FourA-Limit`ヘッダーを付けて応答します。

**解決策:** `retryAfter`秒待ってから、リトライしてください:

```python
import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")
```

容量上限による 503 は FourA 側の混雑を示しているため、バックオフしてリトライすることが唯一の対処法です。代わりに 429 と `X-FourA-Limit` で拒否される場合は、クライアント側の問題です。パイプライン内の並列リクエスト数を減らしてください。

## 504 アップストリームのタイムアウト

**症状:** API が `{"error": "Upstream timeout"}` を含む 504 を返します。

**原因:** リクエストに指定された時間内に処理が完了しませんでした。ターゲットの応答遅延、コールド状態からのチャレンジ解決、または非常に大きなページが原因となります。API キー、パラメータ、プロキシの問題ではありません。

**解決策:** 呼び出しの制限時間を延長するか、リトライしてください。FourA は `timeout_ms` にわずかなマージンを加えた時間待機するため、これを増やすと待機時間が実際に延長されます。

```json
{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}
```

保護されたターゲットに対する `/api/auto/` では、最初のコールドコールに数十秒かかることがあります。その `timeout_ms` はエスカレーション全体をカバーし、最大 180000 まで指定できます。

`/api/auto/` 自体がその予算を使い果たした場合でも、呼び出しは HTTP 200 を返します。ボディには `time budget exhausted` で始まる `error` が含まれ、`status` は通常 504 になります（それ以前の失敗した試行のステータスが残ることもあります）。`timeout_ms` の値を引き上げるか、再試行してください。

## 502 アップストリーム利用不可

**症状:** API が `{"error": "Upstream unavailable"}` とともに 502 を返すか、`{"error": "Backend service unavailable"}` とともに 503 を返します。

**原因:** FourA が自身のエンジン（`Upstream unavailable`）に接続できなかったか、エンジンが利用可能な応答を返しませんでした（`Backend service unavailable`）。通常はインスタンスの再起動が原因です。`/api/browser/` では、すべてのブラウザがビジー状態の場合、ページは空きブラウザを最大 10 秒間待機し、それでも待機が続くページはこの 503 として返されます。

**解決策:** 短いバックオフを挟んで再試行してください。どちらも `service_error` として分類され、課金されるのは `success` のみであるため、再試行に追加のコストは発生しません。問題が 1〜2 分以上続く場合は、[ステータスページ](https://updates.foura.ai/status)を確認してください。

## 401 認証エラー

**症状:** すべてのリクエストが 401 Unauthorized を返します。

**チェックリスト:**
1. ヘッダーが `X-API-Key: YOUR_API_KEY` であることを確認します（`Authorization: Bearer` や `Api-Key` ではありません）
2. API キーに余分な空白や改行が含まれていないか確認します
3. 現在のキーが侵害されている可能性がある場合は、[ダッシュボード](https://foura.ai/dashboard)から新しいキーを作成します

## 400 無効なリクエスト

**症状:** `POST /api/single/`、`/api/proxy/`、または `/api/browser/` の呼び出しが `{"error": "Invalid request: <field>: <reason>; ..."}` とともに 400 を返します。

**原因:** リクエストボディのフィールドが不足している、型が正しくない、または範囲外です。エラーメッセージには、受け入れられなかったフィールドとその理由が最大 5 つまで示され、それ以上ある場合は続いて `and N more` が表示されます。データは取得されず、結果は `client_error` となり、クレジットは消費されません。

**解決策:** 指定されたフィールドを修正してリクエストを再送信してください。同じボディでは同じ 400 が返されるため、変更せずに再試行しないでください。[エンドポイントリファレンス](https://foura.ai/docs/api/endpoints)には、各フィールドの型と制限が記載されています。`/api/auto/` では、同じミスが HTTP 200 として返され、`status: 400` および `error` に理由が含まれます。

## 400 ターゲットがプライベートまたは予約済みIPに解決される

**症状:** リクエストが FourA を離れる前に、API が `Refusing to fetch <target>: target resolves to a private or reserved IP range` とともに 400 を返します。

**原因:** `url` がプライベート、ループバック、または予約済み IP レンジ（RFC 5735、RFC 6598、または IPv6 予約ブロック）に解決されます。FourA のネットワークが内部ホストへのアクセスに使用されるのを防ぐため、FourA はこれらのターゲットを拒否します。

**解決策:** パブリック URL を取得してください。テストを行う場合は、`https://example.com` や `https://httpbin.org/get` などのパブリックターゲットを使用してください。対象のターゲットが自身で実行しているサービスである場合は、まずパブリックホスト名で公開してください。

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

名前解決できないホスト名は拒否されません。FourAが到達できない他のターゲットと同様、呼び出しは`status: 0`と理由 (`could not resolve <host>: <reason>`) を含むHTTP 200として返され、課金は発生しません。

## 400 URL内のスペース

**症状:** リクエストがFourAから送信される前に、Single、Proxy、またはAutoが`invalid URL: it contains a space; encode it as %20 (the URL as sent: "...")`を含む400を返します。

**原因:** URL内にスペースまたは制御文字が含まれています。通常、ページからそのまま取得したリンク (`javascript: void(0)`、テキストを含む共有リンクなど) が原因です。フェッチは実行されず、結果は`client_error`となり、クレジットは消費されません。

**解決策:** 送信前にURLをエンコードし (スペースは`%20`)、`javascript:`などのページではないリンクをスキップします。BrowserはChromeと同様の方法でこのようなURLをフェッチします。

## 400 ターゲットがFourA API自体になっている

**症状:** リクエストがFourAから送信される前に、APIが`Refusing to fetch <url>: that is the FourA API itself, not a page.`を含む400を返します。

**原因:** `url`が`api.foura.ai`または`eu.api.foura.ai`を指しています。クローラーがページの相対リンクをページ自体のURLではなくAPIのURLに対して解決した場合に発生しやすく、`/category/news/`が`https://eu.api.foura.ai/category/news/`に変換されます。フェッチは実行されず、クレジットは消費されません。

**解決策:** 送信前に、Pythonの`urljoin(page_url, href)`などを使用して、すべてのリンクを取得元ページのURLに対して解決します。[Inspect endpoint](https://foura.ai/docs/api/inspect) (`/inspect`) は、FourA経由でフェッチ可能なAPIホスト上の唯一のアドレスです。

## exitCountries使用時のno_eligible_proxy

**症状:** `exitCountries`を指定した`/api/proxy/`の呼び出しが、JSONエラーエンベロープを含むHTTP 200を返します:

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

**原因:** 現在のproxyプールには、ターゲットから認識される国が許可リストと一致する有効な出口が存在しません。標準プールでは、`exitCountries`を設定した場合にリクエスト外の国へフォールバックすることはありません。`exitCountries`がない場合、同様の状況では`{"error": "Failed"}`が返されます。FourAに試行可能な出口がなかったため、数秒後に再試行してください。

出口の場所を指定するリクエスト (`exitState`、`exitCity`、`exitAsn`、`exitOs`、または`exitClass: premium`を伴う`exitLifetimeMin`) は、プレミアム出口経由でのみ送信されます。FourAで試行可能なプレミアム出口が残っていない場合、呼び出しは`"error": "No premium exit answered for this request"`および同一の`code: no_eligible_proxy`で終了します。

**解決策:** 指定したスコープを維持したまま、後で再試行してください。プールは約10分ごとに更新されるため、現在一致するものがない国でも、通常は1時間以内に利用可能になります。

```python
import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
```

ワークフローの国要件が実際に変更された場合にのみ、国のリストを広げてください。他国へのサイレントフォールバックは、ダウンストリームの地理依存ロジックを破壊する可能性があります。

## ブラウザプロファイルが拒絶される

**症状:** 呼び出しが `unknown profile '<id>'`、`no profile matches browser=...`、または `browser profile selection requires unblocker:true` を返します。

**原因:** 送信した `profile`、`browser`、`os`、または `version` がカタログに存在しないか、`unblocker: false` と共に送信されました。

**解決策:** 現在のカタログについて [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles) を確認してその中から選択し、ブラウザを選択する際は `unblocker` を有効にしておきます。

## レスポンスボディが文字化けして返される

**症状:** ターゲットが非 UTF-8 文字セットを使用している場合、レスポンスの `data`（または `body`）に文字化けや判読不能な文字が含まれます。

**原因:** デフォルトでは、FourA はターゲットの `Content-Type` ヘッダーまたは HTML の `<meta charset>` タグに基づいて、レスポンスボディを UTF-8 に自動デコードします。ターゲットが文字セットについて誤った情報を返すと、テキストが文字化けします。

**解決策:** バイナリペイロード（画像、protobuf、raw オーディオ）の場合、リクエストで `returnBuffer: true` を設定してください。Single および Proxy は、文字セット変換を適用せず、生バイトを保持するオブジェクトとして `data`（`{"type": "Buffer", "data": [<byte values>]}`）を返します。

```json
{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}
```

charsetの宣言が誤っているテキストターゲットの場合は、raw bytesをご自身でデコードしてください。`returnBuffer: true`で取得し、`data.data`のバイト値を読み取った後、正しいcharsetでデコードします。

## JSONではなく予期しないHTMLが返される

**症状:** ターゲットサイトからJSONを期待していたが、HTMLが返された。

**原因:** ターゲットページがheadersに基づいて異なるコンテンツを提供している可能性があります。

**解決策:** `Accept` headerを追加し、`unblocker`を有効にしてリアルなブラウザheadersを送信します。

```bash
curl -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://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'
```

`tryJsonData` を `true` に設定して、FourA に JSON レスポンスを自動パースさせることもできます。

## ボディがコンテンツではなくチャレンジページになっている

**症状:** 呼び出しは成功し、`status` は 200 ですが、`data`（または `body`）が目的のページではなく bot チェックになっています。

**原因:** ターゲットが bot チェックを実行し、FourA はそれを検出したもののクリアできませんでした。レスポンスにその旨が示されます。Single および Proxy は `solved: false` を含む `defense` を返し、Browser は `defenses.present` にベンダー名を含む `defenseSolved: false` を返します。

**解決策:** まず `defense.vendor` を確認し、その後エスカレーションしてください。Single で別のブラウザプロファイルを試すか、別のイグジットを使うために Proxy へ移行するか、JavaScript を実行するために Browser を使用します。完全なフィールドリファレンスとベンダー一覧: [サイトチェック](https://foura.ai/docs/api/site-checks)。

実際のページにのみ存在する `validate.data.accept` 部分文字列を追加してください。FourA が認識したチェックページは成功として扱われません。`X-FourA-Check-Page` ヘッダー付きで返され、課金されません。`validate` を設定しない場合、HTTP 200 で返される FourA が認識できないチェックページは成功とみなされ、呼び出し時ではなく後続処理で発覚することになります。

## 解決しない場合

上記の方法で解決しない場合:

1. [ステータスページ](https://updates.foura.ai/status) で進行中のインシデントがないか確認してください
2. [ダッシュボード](https://foura.ai/dashboard) でリクエストメトリクスを確認してください
3. リクエストの詳細（失敗したレスポンスの `X-FourA-Request-Id` を含む）を添えて support@foura.ai までお問い合わせください

## 次のステップ

- [エラーハンドリング](https://foura.ai/docs/api/errors): API エラーコードリファレンス
- [レート制限](https://foura.ai/docs/api/rate-limits): 各プランおよびプラットフォームの制限とフィールド
- [リクエスト結果](https://foura.ai/docs/api/outcomes): 結果がどのように分類されるか
- [サイトチェック](https://foura.ai/docs/api/site-checks): `defense` フィールドが示す内容
- [適切なエンドポイントの選択](https://foura.ai/docs/guides/choosing-task-type): ターゲットに応じた最適なアプローチの選択
- [ダッシュボードの概要](https://foura.ai/docs/dashboard/overview): リクエストのモニタリング
