レート制限

すべての FourA API request は rate limit の対象となります。制限には、concurrency（同時実行数）と RPM（1分あたりの request 数）の2種類があります。どちらもサービスごとに適用されます。

rate limit の仕組み

API は2つのレベルで制限を適用します：

1. グローバル API 制限: endpoint に関わらず、すべての request に適用されます。このチェックが最初に実行されます。
2. サービスごとの制限: 各 endpoint（single、proxy、browser）に個別に適用されます。このチェックは、グローバル制限を通過した場合にのみ実行されます。

グローバル制限に達した場合、サービスごとのチェックは実行されません。request がバックエンドに到達するには、両方のチェックを通過する必要があります。

各レベルは2つのメトリクスを追跡します：

• Concurrency: 同時に実行されている request の数。
• RPM: 過去60秒間に送信された request の数。

rate limit レスポンス

制限に達すると、API は現在の使用状況と適用されている制限を含む JSON response を返します。

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: Concurrency 超過

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

同時に実行されている request が多すぎます。以前の request の一部がまだ完了していません。

サービス無効化

メンテナンスのためにサービスが一時的にオフラインになると、API は異なるエラーメッセージとともに 503 を返します：

{
  "error": "Service disabled",
  "status": 503,
  "retryAfter": 60
}

これは rate limit ではありません。サービスが一時的に利用できなくなっています。retryAfter の値を確認し、その秒数だけ経過した後に再試行してください。通常、これは数分以内に解決します。

これを concurrency による 503 と混同しないでください。"Service disabled" response には current や limits フィールドは含まれません。

response フィールド

rate limit の処理

バックオフを実装するには、retryAfter フィールドを使用します：

import requests
import time

def fetch(url, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={"method": "GET", "url": url}
        )

        if resp.status_code in (429, 503):
            data = resp.json()
            wait = data.get("retryAfter", 5)
            time.sleep(wait)
            continue

        return resp

    raise Exception("Max retries exceeded")

ヒント

• rate limit レスポンスの current フィールドを確認して、使用パターンを把握します。
• 継続的に concurrency 制限に達する場合は、並行 request 数を減らしてください。
• RPM 制限に達する場合は、request 間にわずかな遅延を追加するか、より長い時間枠に分散させてください。
• retryAfter の値は制限の種類によって異なります。concurrency の場合は2秒、RPM の場合は5秒です。
• "Service disabled" response はメンテナンス中であることを意味します。endpoint への連続したアクセスは避けてください。

関連情報

• API Endpoints: 完全なパラメータリファレンス
• Error Handling: すべてのエラータイプとレスポンス
• Troubleshooting: 一般的な問題と解決策