レート制限
すべての FourA API リクエストは、エンジンに到達する前に3つのチェックを通過します。まず契約プランの制限、次に全トラフィックに対するプラットフォームの共有枠、そして呼び出した endpoint に対するプラットフォームの共有枠です。各チェックは個別にリクエストを拒否でき、それぞれ異なるボディで応答します。
3つのチェック(評価順)
- プラン制限。 ご利用のプランで許可されている内容。含まれる endpoint やパラメータ、endpoint ごとに同時実行可能なリクエスト数、1分あたりのリクエスト数、1日あたりのブラウザリクエスト数、請求期間内で利用可能なクレジットおよび帯域幅などです。
- グローバルプラットフォーム制限。 トラフィックの送信先 endpoint を問わず、呼び出し先の API ホストがその瞬間に処理している全体負荷。ここでの拒否は
"service": "api"を返します。 - Endpoint ごとのプラットフォーム制限。 呼び出された Single、Proxy、または Browser サービス上のトラフィック。
契約プランが最初に判定されます。この順序は実装の詳細ではなく仕様(コントラクト)です。共有枠は共有リソースであるため、プラットフォーム側で最終的に拒否されるはずのリクエストが、拒否に至る過程でこれらを消費してはなりません。プラン上限を大幅に超えて送信しているアカウントは、他者が利用するリソースに影響を与える前に遮断されます。
チェック2と3は、お客様のリクエストではなく FourA の総トラフィックをカウントします。これらによる拒否は「送信量が多すぎる」ではなく、「FourA が混雑している」と解釈してください。チェック1はお客様のアカウントのみを対象とし、プラットフォーム上の他の要素によって変動することはありません。
いずれかの共有チェックで拒否された場合、リクエストはバックエンドに到達しなかったため、承認時にカウントされた1分あたりのバケットやブラウザの日次スロットなどはすべてアカウントに返却されます。Requests per minute で説明されているリトライ待機時間にもカウントされません。プランではなく FourA のキャパシティによって拒否されたためです。
POST /api/auto/ 自体はスロットを保持しません。内部で実行される Single、Proxy、Browser の各サブコールは他のリクエストと同様に3つのチェックすべてを通過するため、auto コールの並行バッチはサブコールを通じてプランにカウントされます。(リクエスト数と成功率では auto コール自体が1回としてカウントされ、サブコールはその試行として表示されます。)
プラン制限
プラン制限による拒否では、呼び出しを拒否した制限項目を示す X-FourA-Limit ヘッダーが返されます。ヘッダーを読み取らずに分岐処理ができるよう、同じコードがボディの reason にも含まれます。すべてのプラン制限ボディには error、reason、documentation が含まれ、その他のフィールドは制限の種類によって異なります。
X-FourA-Limit |
ステータス | 原因 |
|---|---|---|
plan_limit_feature |
403 | 呼び出した endpoint、または exitCountries、exitState、exitCity、exitAsn、exitOs パラメータがプランに含まれていません |
plan_limit_premium |
403 | exitClass: premium がプランに含まれていないか、プレミアムトラフィックの残量がない状態で Proxy request が exit location を指定しています |
plan_limit_concurrency |
429 | その endpoint に対する同時リクエスト数制限 |
plan_limit_rate |
429 | その endpoint に対する 1 分あたりのリクエスト数制限 |
plan_limit_browser_daily |
429 | 1 日あたりのブラウザリクエスト数制限 |
plan_limit_credits |
429 | 請求期間内の課金対象クレジット制限 |
plan_limit_bandwidth |
429 | 請求期間内の帯域幅制限 |
各制限の具体的な数値はプランに基づきます。Usage & Limits の Limits & Features タブで、現在の使用状況と並んで表示されます。値をハードコードしないでください。拒否されたすべてのレスポンスには、上限となった制限値が含まれます。
拒否された request ではクレジットを消費しません。結果は rate_limit となり、success のみが課金対象となります。
プランに含まれていない endpoint またはパラメータ
plan_limit_feature を伴う 403 は、プランに含まれない機能が呼び出しで要求されたことを意味します。このチェックはカウント処理の前に実行されるため、拒否された呼び出しが rate limit や日次カウンターに影響することはありません。
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
ジオターゲティングのないプランで exitCountries、exitState、exitCity、exitAsn、または exitOs を設定する POST /api/proxy/ 呼び出しに対しても、同じコードとステータスが返されます。error 文字列に対象のパラメータ名が含まれます。
{
"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"
}
プレミアム出口を含まないプランにおける exitClass: premium に対しても、plan_limit_premium は同じ形式になります。プレミアム出口を含むものの今期のプレミアムトラフィックを使い切ったプランの場合、Proxy requestが出口ロケーションを指定していない限り、拒否されることはありません。リクエストは標準プールから処理され、レスポンスには exitClass: standard が報告されます。いずれの場合もプレミアム出口は消費されません。exitClass を参照してください。
どちらの 403 でも Retry-After は設定されません。待機しても結果は変わりません。
同時リクエスト
同時実行数は endpoint ごとにカウントされます。プランには Single 用、Proxy 用、Browser 用の各上限が個別に設定されています。上限を超えたリクエストは、Retry-After: 1 を伴う 429 として返されます。
{
"error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
"reason": "plan_limit_concurrency",
"documentation": "https://foura.ai/prices",
"limit": 50,
"in_flight": 51,
"retry_after_seconds": 1
}
in_flight は拒否されたリクエストもカウントするため、limit よりも少なくとも1つ多く読み取られます。
解決策は、リトライを強化するのではなく、独自の並列処理数を制限することです。429 に対して同じバッチを即座に再送信すると、その中のすべての呼び出しで再び 429 が発生します。実用的なパターンについては リクエストを並列で実行する を参照してください。
分あたりのリクエスト数
Single および Proxy には、スライディング方式の1分間で測定される分あたりの許容量があります。承認されたリクエストのみがカウント対象となります。拒否されたリクエストは除外されるため、許容量をわずかに超えて安定してリクエストを送信するアカウントでも、ほぼすべてが拒否されるのではなく、許容量までは処理されます。
{
"error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 613,
"retry_after_seconds": 17
}
retry_after_seconds は、その間に追加のリクエストを送信しなかった場合に、次の1件のリクエストが許可されるまでの待機時間を示します(最小1秒、最大120秒)。Retry-After ヘッダーにも同じ値が含まれます。
拒否されたリクエストをそれより早いタイミングで再試行する場合には、固有のルールが適用されます。直近1分間のスライディングウィンドウ内でこの許容量によって拒否されたリクエスト数が許容量の2倍を超えると、呼び出しは代わりに30秒の待機時間で拒否されます。
{
"error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 540,
"refused_last_minute": 1250,
"cooldown": true,
"retry_after_seconds": 30
}
一時停止中の拒否はカウントされないため、クライアントが再試行を続けた場合でも、分が進むにつれて一時停止は自然に終了します。一時停止と通常の許容量を区別するには、errorのテキストではなくcooldownを読み取ってください。
1日あたりのBrowserリクエスト
Browserには分単位の許容量がありません。プラン制限はUTC午前0時からカウントされる1日あたりのBrowserリクエスト数であり、メーターは成功したものだけでなく、受け入れられたすべてのBrowserリクエストをカウントします。503 Backend service unavailableなど、FourA側でゼロクレジットで失敗したBrowser呼び出しは、その日のスロットを返却します。制限によって拒否されなかったBrowserおよびAutoの応答には、X-FourA-Browser-Used-TodayおよびX-FourA-Browser-Limit-Per-Dayヘッダーにカウントと制限が含まれます。Response Headersを参照してください。
{
"error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
"reason": "plan_limit_browser_daily",
"documentation": "https://foura.ai/prices",
"limit_per_day": 300,
"used_today": 301
}
この拒否にはretry_after_secondsおよびRetry-Afterヘッダーは含まれません。待機時間が数秒ではなく数時間におよぶためです。停止として扱い、次回の実行をUTC午前0時にスケジュールしてください。
請求期間のクレジット
請求対象のクレジットのみがカウントされます。つまり成功したリクエストのみです。請求総額が今期利用可能なクレジットに達すると、期間がリセットされるか追加購入するまで、以降のリクエストは拒否されます。
{
"error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 75000,
"hard_stop": 75000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
hard_stop は、今期のリクエストが停止する請求対象クレジット数です。自身で計算するのではなく、body から読み取ってください。プランに追加購入したクレジットがすでに含まれています。
請求期間の帯域幅
帯域幅上限のあるプランでは、今期の標準トラフィックが上限に達するとリクエストが拒否されます。プレミアムトラフィックには独自の使用枠があり、この上限にはカウントされません。購入した帯域幅はプラン付属の帯域幅と同様にカウントされ、error 文字列にはプラン付属分のみではなく、利用可能な総量が表示されます。
{
"error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
"reason": "plan_limit_bandwidth",
"documentation": "https://foura.ai/prices",
"used_bytes": 53687091200,
"limit_bytes": 53687091200,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
両方の期間制限において、retry_after_secondsの上限は24時間です。resets_atは期間が更新される正確な日時です。
プラン制限フィールド
| フィールド | 型 | 含まれる対象 | 説明 |
|---|---|---|---|
error |
string | すべて | 適用される制限値を含む、人間が読める形式のメッセージ |
reason |
string | すべて | plan_limit_および制限名。X-FourA-Limitヘッダーと同じ値。 |
documentation |
string | すべて | プランページへのリンク |
retry_after_seconds |
number | concurrency, rate, credits, bandwidth | 待機時間。Retry-Afterヘッダーと同じ値。 |
limit |
number | concurrency | そのendpointでプランが許可する同時リクエスト数 |
in_flight |
number | concurrency | 拒否されたものを含め、アカウントのそのendpointで実行中のリクエスト数 |
limit_per_minute |
number | rate | そのendpointでプランが許可する1分あたりのリクエスト数 |
current_rate |
number | rate | 拒否されたものを含め、直近1分間でカウントされたリクエスト数 |
refused_last_minute |
number | rate pause | 直近1分間に1分あたりの許容量を超えて拒否されたリクエスト数。30秒間の一時停止時のみ。 |
cooldown |
boolean | rate pause | 再試行間隔が短すぎることによる30秒間の一時停止時はtrue。通常のリクエスト制限超過時は含まれません。 |
limit_per_day |
number | browser daily | プランが許可する1日あたりのブラウザリクエスト数 |
used_today |
number | browser daily | 拒否されたものを含め、本日カウントされたブラウザリクエスト数 |
used |
number | credits | 今期これまでに請求されたクレジット数 |
hard_stop |
number | credits | 今期リクエストが停止する請求クレジット数 |
used_bytes |
number | bandwidth | 今期これまでの標準トラフィック(バイト単位)。Premiumトラフィックは含まれません。 |
limit_bytes |
number | bandwidth | 今期利用可能なバイト数 |
resets_at |
string | credits, bandwidth | 期間終了のISO 8601タイムスタンプ |
プラン制限ではretry_after_secondsが使用されます。後述のプラットフォーム制限ではretryAfterが使用されます。リトライ処理では両方を読み取るか、プラン制限および503 API key check temporarily unavailableで設定されるRetry-Afterヘッダーを読み取る必要があります(エラーを参照)。
プラットフォーム制限
プラットフォームチェックは、サービスごとに2つの項目を追跡し、全サービス全体でさらにもう1つの項目を追跡します。
- Concurrency: FourAが同時に実行しているリクエスト数。
- RPM: FourAが過去60秒間に受信したリクエスト数。
どちらのカウンターも、そのサービスを利用している全員で共有されます。以下のレスポンスに含まれるcurrentおよびlimitsは、アカウントではなくプラットフォーム全体の状態を示しています。自身のアカウントの数値を確認したい場合は、プラン制限レスポンスからin_flightを読み取るか、ダッシュボードの使用量と制限を開いてください。
429: RPM超過
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": {
"concurrency": 12,
"rpm": 3000
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
サービスは直近1分間の許容request数に達しました。retryAfter秒待機してください。
503: 同時実行数の上限超過
{
"error": "Service at capacity",
"status": 503,
"service": "proxy",
"retryAfter": 2,
"current": {
"concurrency": 500,
"rpm": 1200
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
サービスは同時に実行可能な上限数のリクエストを処理しています。これは数秒で解消されます。
サービスの停止
メンテナンスのためにサービスが一時的にオフラインになると、APIは別のエラーメッセージとともに503を返します。
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
これはレート制限ではありません。サービスが一時的に利用不可となっています。retryAfterの値を確認し、その秒数待機してから再試行してください。通常は数分以内に解決します。
両方の503形式は同じキーを持つため、存在するフィールドではなく、必ずerror文字列で分岐してください。Service disabledはメンテナンス、Service at capacityは同時実行数の制限を示します。
メンテナンス形式では、current.concurrencyおよびcurrent.rpmは常に0になります。測定が行われる前にリクエストが拒否されました。
プラットフォーム制限フィールド
| Field | Type | Description |
|---|---|---|
error |
string | 人間が読み取り可能なエラーメッセージ |
status |
number | HTTPステータスコード (429または503) |
service |
string | 呼び出しを拒否したサービス: single, proxy, browser, または api |
retryAfter |
number | 再試行前の推奨待機時間 (秒) |
current.concurrency |
number | 拒否時にサービスが全顧客にわたって実行中だったリクエスト数 |
current.rpm |
number | 過去60秒間にサービスが全顧客にわたって受け付けたリクエスト数 |
limits.maxConcurrency |
number | サービスの共有同時実行許容量 |
limits.maxRpm |
number | サービスの1分あたりの共有許容量 |
1つのヘルパーですべての拒否を処理する
待機する価値のあるプラン制限にはRetry-Afterが設定され、その本文にはretry_after_secondsが含まれ、プラットフォームの本文にはretryAfterが含まれます。この順序で3つすべてを読み取り、待機しても解消されないプラン制限では処理を中断してください。
import time
import requests
# Plan limits that a short wait never clears.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def wait_seconds(resp, attempt):
header = resp.headers.get("Retry-After")
if header and header.isdigit():
return int(header)
try:
body = resp.json()
except ValueError:
return 2 ** attempt
return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
def fetch(url, api_key, max_retries=5):
for attempt in range(max_retries):
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},
)
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")
if resp.status_code in (429, 503):
time.sleep(wait_seconds(resp, attempt))
continue
return resp
raise RuntimeError("Max retries exceeded")
日次利用枠は数時間、期間利用枠は数日間にわたり回復しないため、待機ではなく停止として処理してください。次回の実行をスケジュールする場合は、bodyからresets_atを読み取ります。
ヒント
- 拒否されたバッチを再試行するのではなく、インフライトのリクエスト数を制限してください。リトライストームは、1つの429を多数の429へと拡大させます。
- まず
X-FourA-Limitを確認してください。その制限が利用者のものかプラットフォームのものかが1つの文字列で示され、プラットフォーム側の拒否でこれが設定されることはありません。 - 数値をハードコードしないでください。プラン制限のすべてのレスポンスには拒否の原因となった上限値が含まれており、Usage & Limitsですべて確認できます。
- プラットフォーム制限での
retryAfterは種別ごとに固定です。同時実行数は2秒、RPMは5秒、メンテナンスは60秒です。 - 2種類の503を識別するには
errorで照合してください。どちらの形式にもcurrentとlimitsが含まれるため、「それらのフィールドが存在するか」だけのチェックでは、メンテナンスが同時実行数の問題として誤認されます。 X-FourA-Limitを伴う403はプランに関するものであり、ターゲットサイトに関するものではありません。ターゲットは応答していません。
プロキシポートの個別制限値
上記の内容はすべてJSON APIに関するものです。proxy.foura.ai経由で送信されるトラフィックには、異なる単位による別のプラン制限値が適用されます。具体的には、同時オープン接続数、1分あたりの接続開設数、および請求期間の標準トラフィックです。CONNECTには格納するbodyが存在しないため、これらの拒否はJSON bodyではなくX-Foura-Errorヘッダーを伴うHTTPステータスとして返されます。ステータス一覧についてはProxy Portを、ポートのギガバイト消費元となるプールについてはHow Your Plan Is Meteredを参照してください。
関連情報
- Run Requests in Parallel: 同時実行数制限の実装パターン
- Usage & Limits: すべてのプラン制限とリアルタイムの使用状況
- API Endpoints: パラメーター完全リファレンス
- Error Handling: すべてのエラータイプとレスポンス
- Response Headers:
X-FourA-Limit、Retry-After、およびその他のヘッダー - Troubleshooting: よくある問題と解決策