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

内容为空或不完整

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

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

解决方案: 从单 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"
  }'

注意:browser endpoint 在 body 字段中返回内容(而非 data)。

403 Forbidden 或验证页面

现象: API 返回包含验证页面或拒绝访问页面的 HTML。

原因: 目标网站检测到该请求为自动化操作并进行了拦截。

解决方案: 使用 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 轮换提供更多重试次数。

目标返回的 403 会作为 HTTP 200 返回,并在 body 中包含 status: 403。调用本身的 403 包含 X-FourA-Limit header,属于不同情况:请参阅 403 Not in Your Plan。

超时错误

症状: request 失败并返回超时错误。

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

解决方案: 调大 timeout_ms(默认单次 request 为 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
  }'

对于浏览器 request,还需验证 checkText 的值确实出现在页面上。拼写错误会导致调用失败并返回 checkText:<your text> not found。

403 不在您的套餐内

症状: API 返回 403,并带有 X-FourA-Limit header 以及值为 plan_limit_feature 或 plan_limit_premium 的 reason。

{
  "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,以及在高级流量耗尽后指定 出口位置 的 Proxy 请求。目标未被访问,也没有产生扣费。

解决方案: 移除该参数、调用套餐内包含的 endpoint,或升级套餐。用量与限额 的 限额与功能 标签页列出了您套餐包含的内容。请勿原样重试:由于等待不会改变结果,因此未设置 Retry-After。

429 请求过多

现象: API 返回 429。

原因: 两种检查机制之一拒绝了调用,response 会指出是哪一种。如果携带 X-FourA-Limit header,则表示达到了套餐的某项限额:该 endpoint 的并发 request 数或每分钟 request 数、当天的 Browser request 数,或账单周期的积分或带宽。若没有该 header,则表示该服务的平台共享每分钟配额已满,这与 FourA 的总体流量有关,与您的流量无关。

解决方案: 先查看 X-FourA-Limit。如果限额在数秒内即可解除,请等待;否则请停止。可通过等待恢复的套餐限额会将秒数放入 Retry-After header 和 retry_after_seconds 中;共享限额则会将其放入 retryAfter 中:

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

如果 header 显示为 plan_limit_concurrency 或 plan_limit_rate,解决方法是限制保持打开的调用数量以及每分钟发起的调用数量,而不是加大重试力度。立即重新发送被拒绝的批次会导致整批再次被拒。被拒绝的调用不会计入每分钟限制,但如果到达速率持续超过该限制的两倍,拒绝将转为冷却期:429 body 会携带 cooldown: true,并要求暂停 30 秒(retry_after_seconds: 30)。Run Requests in Parallel 提供了相应模式,Dashboard 中的 Usage & Limits 会在上限旁显示实时计数器。

503 服务不可用

症状: API 返回 503 状态。

原因: 存在以下三种情况:

  1. 服务达到容量上限。 FourA 在该引擎上同时运行的 request 数量已达上限,该上限统计所有流量而非仅针对个人。error 字段为 Service at capacity。通常几秒内恢复。
  2. 服务暂时停用。 正在进行维护。error 字段为 Service disabled。
  3. FourA 暂时无法验证密钥。 error 字段为 API key check temporarily unavailable,伴随 Retry-After: 5。密钥本身有效。

这三种情况都会在 response 中包含 retryAfter 字段。均不属于套餐限制:个人套餐限制始终会在 403 或 429 上返回 X-FourA-Limit header,绝不会返回 503。

解决方案: 等待 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):
            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 返回 504 以及 {"error": "Upstream timeout"}。

原因: 任务未在您为请求声明的时间预算内完成。目标站点响应缓慢、冷启动验证求解或页面体积过大都会导致该问题。这与您的密钥、参数或代理无关。

解决方案: 为调用分配更多时间,或重试。FourA 会等待您设置的 timeout_ms 加上一个较小的缓冲时间,因此调高该值确实会延长等待时间:

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

对于受保护目标上的 /api/auto/,首次冷调用可能需要数十秒。其 timeout_ms 覆盖整个阶梯重试流程,最高可接受 180000。

当 /api/auto/ 自身耗尽该预算时,调用仍会返回 HTTP 200。响应 body 包含以 time budget exhausted 开头的 error,且 status 通常为 504(较早失败的尝试可能会在其中留下其自身的状态)。请提高 timeout_ms 或重试。

502 上游不可用

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

原因: FourA 无法连接到其自身引擎 (Upstream unavailable),或引擎未返回可用响应 (Backend service unavailable),通常是因为实例正在重启。在 /api/browser/ 上,当所有浏览器均处于忙碌状态时,页面最多等待 10 秒以获取空闲浏览器,在此之后仍在等待的页面将作为此 503 返回。

解决方案: 使用较短的退避时间重试。两者均归类为 service_error,且仅对 success 计费,因此重试无需额外费用。如果持续超过一两分钟,请查看 状态页。

401 身份验证错误

症状: 每个 request 均返回 401 Unauthorized。

排查清单:

  1. 验证 header 是否为 X-API-Key: YOUR_API_KEY(而非 Authorization: Bearer 或 Api-Key)
  2. 检查 API key 中是否存在多余的空格或换行符
  3. 如果当前密钥可能已泄露,请从 控制面板创建新密钥

400 无效请求

症状: POST /api/single/、/api/proxy/ 或 /api/browser/ 调用返回 400 伴随 {"error": "Invalid request: <field>: <reason>; ..."}。

原因: request body 中的某个字段缺失、类型错误或超出范围。消息会列出每个无法接受的字段及原因,最多显示五个,若有其他字段则后跟 and N more。未抓取任何内容,结果为 client_error,不消耗额度。

解决方案: 修正列出的字段并重新发送 request。相同的 body 会收到相同的 400,因此请勿在未修改的情况下重试。endpoint 参考列出了每个字段及其类型和限制。在 /api/auto/ 上,相同的错误会作为 HTTP 200 返回,包含 status: 400,原因见 error。

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

症状: 在 request 离开 FourA 之前,API 返回 400 伴随 Refusing to fetch <target>: target resolves to a private or reserved IP range。

原因: 您的 url 解析为私有、环回或保留 IP 范围(RFC 5735、RFC 6598 或 IPv6 保留网段)。FourA 会拒绝此类目标,以防其网络被用于访问内部主机。

解决方案: 抓取公开 URL。如果处于测试阶段,请使用公开目标,如 https://example.com 或 https://httpbin.org/get。如果您的目标是您自身运行的服务,请先将其暴露在公开主机名上。

{ "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." }

无法解析的主机名不会被拒绝。该调用返回 HTTP 200,并带有 status: 0 以及原因 (could not resolve <host>: <reason>),与 FourA 无法访问的任何目标相同,且不计费。

400 URL 中包含空格

**症状:**在 request 离开 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 本身

**症状:**在 request 离开 FourA 之前,API 返回带有 Refusing to fetch <url>: that is the FourA API itself, not a page. 的 400。

**原因:**您的 url 指向 api.foura.ai 或 eu.api.foura.ai。爬虫通常会在将页面中的相对链接基于 API URL 而非页面自身的 URL 进行解析时发生这种情况,导致 /category/news/ 变成了 https://eu.api.foura.ai/category/news/。系统不会抓取任何内容,并且不消耗点数。

**解决方案:**在发送前,将每个链接基于其来源页面的 URL 进行解析,例如在 Python 中使用 urljoin(page_url, href)。Inspect endpoint (/inspect) 是 API 主机上唯一可以通过 FourA 抓取的地址。

使用 exitCountries 时出现 no_eligible_proxy

**症状:**带有 exitCountries 的 /api/proxy/ 调用返回包含 JSON 错误外层的 HTTP 200:

{
  "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 没有可尝试的出口,因此请在几秒后重试。

指定了出口位置的 request(exitState、exitCity、exitAsn、exitOs 或 exitLifetimeMin,带有 exitClass: premium)仅通过高级出口发出。当 FourA 没有剩余的高级出口可供尝试时,调用将以 "error": "No premium exit answered for this request" 和相同的 code: no_eligible_proxy 结束。

解决方案: 保留请求的范围并稍后重试。池大约每十分钟刷新一次,因此当前没有匹配项的国家通常会在一小时内恢复可用。

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

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

浏览器 Profile 被拒绝

**症状:**调用返回 unknown profile '<id>'、no profile matches browser=... 或 browser profile selection requires unblocker:true。

**原因:**发送的 profile、browser、os 或 version 不在目录中,或者发送时附带了 unblocker: false。

**解决方案:**查阅 GET /api/profiles 获取当前目录并从中选择,且在选择浏览器时保持 unblocker 处于开启状态。

响应体返回为乱码

**症状:**当目标站点使用非 UTF-8 字符集时,响应 data(或 body)包含乱码或无法读取的字符。

**原因:**默认情况下,FourA 会根据目标站点的 Content-Type 标头或 HTML <meta charset> 标签将响应体自动解码为 UTF-8。如果目标站点未如实声明其字符集,就会出现乱码。

**解决方案:**对于二进制载荷(图片、protobuf、原始音频),请在请求中设置 returnBuffer: true。Single 和 Proxy 随后会将 data 作为包含原始字节的对象 {"type": "Buffer", "data": [<byte values>]} 返回,不执行任何字符集转码。

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

对于字符集声明错误的目标文本,请自行解码原始字节:使用 returnBuffer: true 发起请求,读取 data.data 中的字节值,然后使用正确的字符集对其进行解码。

意外收到 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)是 Bot 验证拦截页面,而不是你所需的内容。

原因: 目标站点触发了 FourA 遇到但未能通过的 Bot 验证。响应已明确指示此状态:Single 与 Proxy 返回包含 solved: false 的 defense,而 Browser 则返回 defenseSolved: false 并在 defenses.present 中指明供应商。

解决方案: 先检查 defense.vendor,然后逐级排查。可以在 Single 上尝试不同的浏览器配置,升级到 Proxy 以使用不同的出口网络,或者使用 Browser 运行 JavaScript。完整字段参考与供应商列表请参阅 站点验证。

添加一个仅真实页面才会包含的 validate.data.accept 子字符串。FourA 能识别的验证页面绝不会被计为成功:它会返回 X-FourA-Check-Page 响应头且不计费。若未配置 validate,FourA 未识别且以 HTTP 200 返回的验证页面将被视为成功请求,导致你只能在下游流程中才发现问题,而无法在调用时立即捕获。

仍未解决?

如果上述方案均无法解决问题:

  1. 查看 状态页面 确认是否存在服务故障
  2. 在 控制台 中查看你的 request 指标
  3. 联系技术支持 support@foura.ai 并附上请求详情(包括失败响应中的 X-FourA-Request-Id)

后续步骤

更新于: 2026年11月13日