速率限制

每个 FourA API request 都会经过速率限制。您会遇到两种限制类型：concurrency（并发请求）和 RPM（每分钟请求数）。两者均针对每个服务分别执行。

速率限制工作原理

API 在两个层面上执行限制：

全局 API 限制：适用于所有 request，无论 endpoint 是什么。此检查首先运行。
单项服务限制：分别适用于每个 endpoint（single、proxy、browser）。只有在全局限制通过时才会运行此检查。

如果触发了全局限制，则不会运行单项服务检查。request 必须同时通过这两项检查才能到达后端。

每个层面都会追踪两个指标：

Concurrency：同时运行的 request 数量。
RPM：您在过去 60 秒内发送的 request 数量。

速率限制响应

当您达到限制时，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
  }
}

您在过去一分钟内发送了太多的 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
}

这不属于速率限制。该服务暂时不可用。请检查 retryAfter 的值，并在相应的秒数后重试。这通常会在几分钟内解决。

请勿将其与 concurrency 503 混淆。“Service disabled” 响应中不会包含 current 或 limits 字段。

响应字段

字段	类型	描述
`error`	string	易于理解的错误消息
`status`	number	HTTP 状态码（429 或 503）
`service`	string	触发限制的服务：single、proxy、browser 或 api
`retryAfter`	number	建议的重试前等待时间（秒）
`current.concurrency`	number	您当前处于活动状态的 request 数量
`current.rpm`	number	您在过去 60 秒内的 request 数量
`limits.maxConcurrency`	number	允许的最大同时 request 数量
`limits.maxRpm`	number	允许的最大每分钟 request 数量

处理速率限制

使用 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")

提示

检查速率限制响应中的 current 字段，以了解您的使用模式。
如果您经常触发 concurrency 限制，请减少并行 request 的数量。
如果您触发了 RPM 限制，请在 request 之间添加微小的延迟，或者在更长的时间窗口内分批发送。
retryAfter 的值因限制类型而异：concurrency 为 2 秒，RPM 为 5 秒。
“Service disabled” 响应意味着正在进行维护。请勿持续频繁请求该 endpoint。