常见问题
使用 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 状态。
原因: 存在以下三种情况:
- 服务达到容量上限。 FourA 在该引擎上同时运行的 request 数量已达上限,该上限统计所有流量而非仅针对个人。
error字段为Service at capacity。通常几秒内恢复。 - 服务暂时停用。 正在进行维护。
error字段为Service disabled。 - 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。
排查清单:
- 验证 header 是否为
X-API-Key: YOUR_API_KEY(而非Authorization: Bearer或Api-Key) - 检查 API key 中是否存在多余的空格或换行符
- 如果当前密钥可能已泄露,请从 控制面板创建新密钥
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 返回的验证页面将被视为成功请求,导致你只能在下游流程中才发现问题,而无法在调用时立即捕获。
仍未解决?
如果上述方案均无法解决问题:
- 查看 状态页面 确认是否存在服务故障
- 在 控制台 中查看你的 request 指标
- 联系技术支持 support@foura.ai 并附上请求详情(包括失败响应中的
X-FourA-Request-Id)