常见问题

使用 FourA API 时最常见问题的解决方案。

内容为空或不完整

症状： API 返回 200 状态，但 data 字段为空或缺少预期内容。

原因： 目标页面在初始加载后使用 JavaScript 渲染内容。

解决方案： 从 single endpoint 切换为 browser endpoint。使用 checkText 验证已加载的内容：

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"
  }'

注意：浏览器 endpoint 将内容返回在 body 字段中（而不是 data）。

403 Forbidden 或 Captcha 页面

症状： API 返回包含 CAPTCHA 质询或拒绝访问页面的 HTML。

原因： 目标网站将 request 检测为自动化操作并将其拦截。

解决方案： 使用 proxy endpoint 进行自动 IP 轮换：

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 轮换提供更多尝试次数。

超时错误

症状： request 因超时错误而失败。

原因： 目标页面加载时间超过了配置的超时时间。

解决方案： 增加 timeout_ms（single 默认为 15s，browser 为 30s，proxy 为 45s）：

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 值是否确实出现在页面上。拼写错误将始终导致超时。

429 Too Many Requests (RPM 限制)

症状： API 返回 429 状态，并带有 "rate limit exceeded" 消息。

原因： 您超出了每分钟请求数 (RPM) 限制。这与并发限制不同 (请参阅下文的 503)。

解决方案： 使用响应中的 retryAfter 字段，等待合适的时间后再重试：

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

在控制台中检查您当前的用量，以查看您的 rate limit。

503 服务不可用

症状： API 返回 503 状态。

原因： 出现此情况有两种可能：

达到并发限制。 您有过多同时运行的 request。这与 429 错误不同，后者限制每分钟的 request 数量。对于 503，您未超出 RPM，但已达到可同时运行的 request 数量上限。
服务暂时停用。 正在进行系统维护。

这两种情况的 response 中均包含 retryAfter 字段。

解决方案： 等待 retryAfter 秒，然后重试：

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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

如果您经常触发 503 并发限制，请减少抓取管道中的并行 request 数量，或在控制台中检查您套餐的并发限制。

504 上游超时

症状： API 返回 504 并包含 {"error": "Upstream timeout"}。

原因： 任务未在您为 request 设定的时间预算内完成。目标响应缓慢、冷启动的验证码挑战或页面过大都会导致此情况。这不是您的密钥、参数或 proxy 的问题。

解决方案： 增加调用时间或重试。FourA 会等待您的 timeout_ms 加上少许容差时间，因此调高该值可切实延长等待时间：

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

对于受保护目标上的/api/auto/，首次冷调用可能需要数十秒。其timeout_ms涵盖整个阶段，最高支持180000。

502 上游不可用

症状： API返回502并伴随{"error": "Upstream unavailable"}，或503并伴随{"error": "Backend service unavailable"}。

原因： FourA到达了其自身引擎但无法使用回复，通常是因为实例正在重启。

解决方案： 使用短暂的退避重试。两者均归类为service_error，且仅对success计费，因此重试不会产生额外费用。如果持续超过一两分钟，请检查状态页面。

401 身份验证错误

症状： 每个请求都返回401 Unauthorized。

检查清单：

验证标头是否为X-API-Key: YOUR_API_KEY (不是Authorization: Bearer或Api-Key)
检查API密钥中是否有额外的空格或换行符
如果当前密钥可能已泄露，请从控制台创建一个新密钥

400 目标解析为私有或保留IP

症状： 在请求离开FourA之前，API返回400并伴随Target <ip> resolves to a private/reserved IP。

原因： 您的url解析为私有、环回或保留IP范围(RFC 5735、RFC 6598或IPv6保留块)。FourA拒绝这些目标，因此其网络无法用于访问内部主机。

解决方案： 获取公共URL。如果您在进行测试，请使用诸如https://example.com或https://httpbin.org/get之类的公共目标。如果您的预期目标是您运行的服务，请首先将其暴露在公共主机名上。

{ "error": "Target <ip> resolves to a private/reserved IP" }

使用 exitCountries 时出现 no_eligible_proxy

**症状：**包含 exitCountries 的 /api/proxy/ 调用返回 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 时，FourA 绝不会回退到未请求的国家。

**解决方案：**保留请求的作用域并稍后重试。代理池大约每十分钟刷新一次，因此目前没有匹配项的国家通常会在一小时内出现可用出口。

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

仅在工作流的国家/地区要求确实发生变化时，才扩大国家/地区列表。静默回退到其他国家/地区可能会破坏下游依赖地理位置的逻辑。

返回的 response body 为乱码

症状： 当目标使用非 UTF-8 字符集时，response data (或 body) 会包含乱码或不可读字符。

原因： 默认情况下，FourA 会根据目标的 Content-Type header 或 HTML <meta charset> 标签将 response body 自动解码为 UTF-8。如果目标声明的字符集不准确，就会出现乱码。

解决方案： 对于二进制 payload (图片、protobuf、原始音频)，请在 request 中设置 returnBuffer: true。body 会作为 base64 buffer 返回，且不进行任何字符集转码。

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

对于错误声明字符集的文本目标，请自行解码原始字节：使用 returnBuffer: true 获取，进行 base64 解码，然后应用正确的字符集。

收到 HTML 而非 JSON

症状： 期望从目标站点获取 JSON，但收到了 HTML。

原因： 目标页面可能会根据 header 返回不同的内容。

解决方案： 添加 Accept header 并启用 unblocker 以使用真实的浏览器 header：

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) 是机器人验证页面，而不是您想要的页面。

原因: 目标网站执行了机器人验证，FourA 遇到但未能通过。响应会指明这一点: Single 和 Proxy 端点返回带有 solved: false 的 defense，Browser 端点返回 defenseSolved: false，并在 defenses.present 中注明供应商。

解决方案: 首先检查 defense.vendor，然后升级策略。尝试在 Single 端点上使用不同的浏览器配置文件，切换到 Proxy 端点以获取不同的出口，或者使用 Browser 端点以运行 JavaScript。完整字段参考和供应商列表: 反机器人防御。

添加一个只有真实页面才包含的 validate.data.accept 子字符串。如果没有它，返回 HTTP 200 的验证页面会被视为成功，您只能在下游发现问题，而不是在调用时。

仍然遇到问题？

如果以上解决方案均无效:

检查状态页面以了解任何正在发生的事件
在仪表板中查看您的请求指标
联系支持团队 support@foura.ai 并提供您的请求详细信息 (包含失败响应中的 X-FourA-Request-Id)

后续步骤

错误处理: API 错误代码参考
请求结果: 结果如何对发生的事件进行分类
反机器人防御: defense 字段告诉您的信息
选择合适的端点: 为您的目标选择最佳方法
仪表板概览: 监控您的请求

更新于： 2026年8月12日