API 错误
如何处理来自 FourA API 的错误。
错误响应格式
API 对所有错误均返回扁平的 JSON 对象。不存在嵌套的 error 对象。若失败包含机器可读的代码,它将作为顶层字段呈现:超出方案配额限制时为 reason,proxy 调用没有符合条件的出口时为 code。
{
"error": "Invalid API key"
}
部分错误在顶层包含额外字段,例如 status、service、retryAfter、current 或 limits:
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": { "concurrency": 12, "rpm": 3000 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
追踪 Request
每个 API response(无论成功还是错误)都包含一个带有该调用 UUID 的 X-FourA-Request-Id header,但 FourA 完全无法读取的 body 除外(格式错误的 JSON 或超过 100 KB 的 body):此类请求在分配 ID 之前即被拒绝。请在您的客户端记录该 ID。如果您需要联系技术支持咨询某个特定 request 的情况,该 ID 能帮助我们定位该请求。
curl -i -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://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
错误类型
400: 错误请求
请求 body 缺少必填字段、包含无效值,或指定了 API 拒绝获取的目标。
不是 JSON 对象或数组的 body 属于格式错误的 JSON,会收到 Invalid JSON in request body,如下所示。
在 Single、Proxy Finder 和 Browser 上,缺失、类型错误或超出范围的字段会在消息中显示为 <field>: <reason>。嵌套字段使用点号连接 (validate.status.accept)。最多列出五个问题,以 ; 分隔,超出部分会在消息末尾以 and <n> more 结束:
{
"error": "Invalid request: url: Invalid input: expected string, received undefined"
}
属于 client_error 且不计费。Auto 则会在 HTTP 200 中报告其无法接受的字段,详见下方的“从 /api/auto/ 读取失败信息”。
同样的 400 状态码也适用于 SSRF 防护。如果您的 url 解析为私有、环回或其他保留 IP 地址范围(RFC 5735、RFC 6598、IPv6 保留块),request 将在离开 FourA 网络之前被拒绝:
{
"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."
}
<target> 是地址,或者是主机名及其解析出的地址。无法解析的 URL,或不是 http:// 或 https:// 的 URL,同样会返回 400。
在 Single、Proxy Finder、Browser 和 Auto 模式下,针对 FourA 自身 API 主机(eu.api.foura.ai 或 api.foura.ai)的目标也会在抓取或扣费之前返回 400。这通常意味着从页面提取的链接被错误解析到了 API URL 而非页面自身的 URL:
{
"error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
<url> 是您发送的原始目标。Inspect 页面是唯一的例外:FourA 仍会为您抓取 https://eu.api.foura.ai/inspect。
包含空格或控制字符的 URL 在 Single、Proxy Finder 和 Auto 上也会返回 400,且在发起抓取或计费之前就会拦截。直接从页面复制的链接通常包含这些字符(javascript: void(0),文本中带有空格的分享链接)。请对其进行编码,将空格转义为 %20。Browser 会像 Chrome 一样抓取此类 URL:
{
"error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
无法解析的主机名不会被拒绝。该调用返回 HTTP 200,并带有 status: 0 以及原因(could not resolve <host>: <reason>),且不计费。FourA 尝试连接但未收到 HTTP 响应的目标(达到重定向限制、连接或读取超时、连接重置)同样返回 HTTP 200,带有 error 和 total_time,且不含 status:参见 请求结果。
在 Single 上,解码后超过 128 MB 的 response body 会在此截断。该调用返回 HTTP 200,带有 "error": "Response body exceeds the 128 MB limit",且不计费。
body 中格式错误的 JSON 会在读取任何字段前以相同方式被拒绝:
{
"error": "Invalid JSON in request body"
}
proxy 和 ignoreProxies 字段有各自对应的 400 错误。两者都接收早期响应返回的不透明 proxy ID,因此其他任何内容都会解码失败:
| 消息 | 原因 |
|---|---|
Invalid proxy format |
proxy 的值不是 FourA 签发的 proxy ID。传入原始代理地址会导致此错误。 |
Invalid ignoreProxies format |
ignoreProxies 中的某个条目不是 proxy ID。 |
Proxy not found |
ID 成功解码,但不再解析到活跃的出口。请选择一个新出口。 |
Managed exit: this proxy id cannot be pinned to a request |
出口真实存在,但 FourA 不会为指定请求保留该出口。当您的套餐没有剩余的高级流量时,传入高级出口 ID 会导致此错误。请复用其返回的 session,或者通过 POST /api/proxy/ 发起调用并接受其选择的任意出口。 |
解决方法: 检查您的 request 是否包含所有必填字段,URL 是否使用 http:// 或 https:// 且空格均已编码为 %20,主机是否解析为公共地址,以及所有 proxy 值是否均为从早期响应中逐字复制的 ID。
这些属于 client_error 结果:request 从未离开 FourA,因此未产生任何扣费。
401:未授权
您的 API key 缺失或无效。
缺少 key:
{
"error": "Missing API key. Include X-API-Key header."
}
无效密钥:
{
"error": "Invalid API key"
}
**解决方法:**验证您的 X-API-Key header 包含有效 key。如有需要,可从 控制台生成新 key。
401 始终表示 FourA 已校验您的 key 并拒绝了请求。当 FourA 在数秒内无法校验 key 时,将返回 503 API key check temporarily unavailable(见下文),绝不会返回 401。
403: 未包含在您的方案中
调用请求了当前方案未包含的 endpoint 或参数。响应会设置 X-FourA-Limit,并在响应体中的 reason 字段返回相同的代码:
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
reason 在遇到套餐未包含的 endpoint,或在不支持地理定位的套餐中使用了 exitCountries 及出口位置字段时为 plan_limit_feature;在未包含高级出口的套餐中使用了 exitClass: premium,或 exit location 已无可用高级流量时为 plan_limit_premium。error 字符串会指明具体的 endpoint 或参数。
来自 FourA 的 403 均与目标网站无关:系统完全未请求目标。目标网站返回的 403 会以 HTTP 200 形式返回,并在 body 中包含 status: 403。
**解决方法:**移除该参数、调用套餐内包含的 endpoint,或升级套餐。此处不会设置 Retry-After,因为重试等待不会改变结果。本次调用未产生计费:结果为 rate_limit,系统仅对 success 计费。
413:请求体过大
JSON 请求体超出了 FourA 允许的大小 (100 KB)。响应并非 JSON 格式,且不包含 X-FourA-Request-Id,因为请求体在被读取前已被拒绝。
**解决方法:**发送更小的 data 负载。本次调用未产生计费。
429:超出速率限制
有两种不同的检查会返回 429,它们包含的字段并不相同。
**您套餐自身的限制。**响应会设置 X-FourA-Limit header 指明拒绝该调用的具体限制项,并在 body 中的 reason 字段提供相同的代码:
{
"error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
"reason": "plan_limit_concurrency",
"documentation": "https://foura.ai/prices",
"limit": 50,
"in_flight": 51,
"retry_after_seconds": 1
}
reason 为 plan_limit_concurrency、plan_limit_rate、plan_limit_browser_daily、plan_limit_credits 或 plan_limit_bandwidth 之一。如果等待有效,等待时间会显示在 retry_after_seconds 以及 Retry-After header 中,绝不会在 retryAfter 中。plan_limit_browser_daily 两者都不包含,因为配额会在 UTC 午夜重置,而不是以秒为单位。不会产生任何扣费:结果为 rate_limit,且仅对 success 计费。
平台的共享配额。 无 X-FourA-Limit header,且等待时间在 retryAfter 中:
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": { "concurrency": 12, "rpm": 3000 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
current 与 limits 描述的是覆盖所有流量的服务状态,而非您的账户状态。此处拒绝表示 FourA 正忙。
解决方法: 等待响应中携带的 Retry-After、retry_after_seconds 或 retryAfter 对应的时间。若遇到并发或速率限制,请限制保持打开的请求数量,而不是重新发送被拒绝的批次。若遇到每日或计费周期限制,请停止运行。有关各字段的详细信息,请参阅 速率限制;有关实现模式,请参阅 并行运行请求。
500: 服务器错误
我们服务端出现异常。
解决方法: 稍后重试请求。如果错误仍然存在,请查看 状态页,或附带失败响应中的 X-FourA-Request-Id 联系支持团队。
502: 上游不可用
FourA 无法从自身引擎获取响应(Upstream unavailable:连接失败),或者收到了无法读取的响应(Malformed JSON from backend)。
{
"error": "Upstream unavailable",
"details": "..."
}
**解决办法:**稍后重试(短退避时间)。这是我们端的问题,因此不收取任何费用:结果为 service_error,并且仅对 success 计费。
504: 上游超时
引擎未能在该请求的时间预算内完成。
{
"error": "Upstream timeout",
"details": "the backend did not finish inside the time budget for this request"
}
504 错误与执行耗时有关,与您的 key、参数或 proxy 无关。常见原因包括目标站点响应缓慢、冷启动验证求解以及大型页面。
解决方法: 调高 request 中的 timeout_ms(Single 支持最高 120000,Browser 最高 120000,Auto 最高 180000),或进行重试。FourA 会等待您声明的超时预算外加少许余量,因此增加时间确实能获得更多处理时间。
503: 服务已禁用或容量已满
503 表示服务因维护暂时不可用,或者平台的并发配额已满。两种情况包含相同的 key:error、status、service、retryAfter、current 和 limits。请通过 error 字符串进行区分,而不是根据包含哪些字段。
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Service disabled 表示维护,且两个计数器的 current 均为 0,因为请求在进行任何统计之前已被拒绝。Service at capacity 是并发形式,其中 current 包含平台的实际用量。有关该数据格式,请参阅 Rate Limits。
解决方法: 等待 retryAfter 秒,然后重试。状态页面列出了当前生效的维护时间窗口。
第三种 503 格式不包含 retryAfter。这意味着您 endpoint 背后的引擎无法接收调用:它可能正在重启、在您的 request 运行之前已在 FourA 侧发生故障,或者(在 Browser 上)在页面等待的 10 秒内所有浏览器实例均处于繁忙状态。backend_status 是引擎自身的状态,detail 是其响应的开头部分:
{
"error": "Backend service unavailable",
"backend_status": 503,
"detail": "..."
}
这是 service_error,且不计费。请在一两秒后重试。本身有误的 request 绝不会进入此状态:它会返回明确指出具体字段的 400 错误。
第四种 503 表示 FourA 暂时无法确认您的 API key,例如在数据库切换期间。您的 key 没有问题,且没有执行任何操作。它带有 Retry-After: 5 以及在 retryAfter 中相同的等待时间:
{
"error": "API key check temporarily unavailable",
"status": 503,
"retryAfter": 5
}
该情况不计费。请在 retryAfter 秒后重试。FourA 在过去 10 分钟内确认过的 key 在此期间会继续有效,因此该响应很少出现。
从 /api/auto/ 读取失败信息
只要阶梯策略已执行,即使每个阶梯环节均失败,POST /api/auto/ 也会返回 HTTP 200。实际结果位于 body 中:
{
"status": 403,
"error": "exit blocked by the target defense",
"attempts": 7,
"meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
status 是目标最后响应的状态码,若无任何尝试成功连接目标则为 502(若超时预算先耗尽则为 504)。已运行阶梯策略的每个失败响应均包含一个统计各尝试所遇情况的 attemptReport,附带一条可安全记录到日志的单行 summary,同时 meta.attemptsByEngine 与 meta.browserRequests 会标明调用发送的内容。请参阅 Auto 调用失败的原因。Auto 无法接受的请求字段(例如 timeout_ms 小于 5000 或大于 180000)也会以相同方式返回:在执行任何尝试之前返回 HTTP 200,包含 "status": 400,并在 error 中说明原因,且不产生任何费用。
因此,对于 Auto 不要根据传输层状态码进行逻辑分支。请改为读取 body 中的 status 与 error。来自 /api/auto/ 的真正非 200 状态码意味着 FourA 在阶梯策略启动前拒绝了调用,或无法完成调用:400(格式错误的 JSON、私有或保留目标、或 FourA 自身 API 主机上的目标)、401、413、502、503 或 504。有一个套餐限制会在入口处直接拦截:在未配置高级出口的套餐上使用 exitClass: premium 会在执行任何操作前收到带有 X-FourA-Limit: plan_limit_premium 的 403。所有其他限制(无论是您的配额还是平台限制)均在 200 响应中返回,其具体状态位于 body 内。
当某个站点连续多次使您的 API key 发起的 Auto 调用失败时,Auto 会在一段时间内直接拒绝该 key 后续对该站点的调用而不进行实际尝试:返回 "error": "target temporarily unservable, retry later"、"status": 503 以及以秒为单位的 retryAfter。这不会产生任何费用;请等待 retryAfter 秒。
某个子调用触发的套餐限制同样以 HTTP 200 返回。body 即为拒绝响应本身,包含其 reason,外加 status 和 meta,且该响应带有与直接拒绝相同的 X-FourA-Limit header:
{
"status": 429,
"error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 75000,
"hard_stop": 75000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z",
"meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
哪些限制会终止阶梯策略,哪些仅关闭单个层级,详见 Smart Fetch (Auto)。
200 OK 内的目标端失败
并非所有失败都会表现为非 2xx HTTP 状态。当目标返回 HTTP 200,但 FourA 的响应携带 error(例如您的 validate 规则拒绝了该 body),或者 body 是 FourA 识别出的验证页面时,结果为 application_error。当目标返回除 200 之外且您的 validate 规则不接受的状态时,结果为 application_fail,并且 body 会原样返回。
这两种情况均不计费:仅对 success 计费。当所有浏览器均处于繁忙状态时,Browser 调用最多等待 10 秒以释放可用实例。如果仍无可用实例,它将返回上述 503 Backend service unavailable。当完全无法获取浏览器时,Browser 也可能返回带有 "error": "No available browser slot" 的 HTTP 200。两者均不计费。请在几秒后重试,或减少同时发起的 Browser 调用数量。Outcomes 参考文档涵盖了完整的分类说明。
通过您指定的 proxy 发起的 Single 调用也可能在 body 旁返回带有 "error": "The exit gave the same answer for <n> different sites" 的 HTTP 200。FourA 检测到该出口向无关站点返回了相同的页面,说明该页面归出口所有,而非您请求的内容。该状态为 application_error 且不计费。请从 POST /api/proxy/ 获取新的出口,它会自动跳过此类出口。
当出口自身的网络代替目标站点响应时也是如此。调用返回 "error": "The exit answered instead of the site (<name>)" 或 "error": "Corporate web gateway intercepted the request (<name>)"(登录页面、过滤页面或指向这些页面的重定向),在出口代站点自身响应时返回 "error": "The exit intercepted TLS and answered instead of the site (<name>)",在出口返回您自身 request 副本时返回 "error": "Honeypot echo proxy (plaintext request dump)"。无论您的 validate 规则如何设定,FourA 都会检查这些情况,包括 returnBuffer 下载。它们均不计费。按相同方式获取新的出口即可。
响应编码
FourA 会自动将 response body 解码为 UTF-8。如果目标服务提供 windows-1251、gbk、shift_jis、iso-8859-*,或在 Content-Type header 或 HTML <meta charset> 标签中声明的任何其他字符集,您将在 data(single、proxy)或 body(browser)字段中收到干净的 UTF-8 字符串。
对于二进制 payload(图像、protobuf、原始音频),请在 request 上设置 returnBuffer: true。Single 和 Proxy 随后会将 data 作为包含原始字节的对象返回({"type": "Buffer", "data": [<byte values>]}),而不应用任何字符集转码。
重试策略
实用的重试策略:
import time
import requests
# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def make_request(url, payload, api_key, max_retries=3):
for attempt in range(max_retries):
resp = requests.post(
url,
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json=payload,
)
if resp.status_code == 200:
return resp.json()
body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
request_id = resp.headers.get("X-FourA-Request-Id", "?")
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")
# Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
header = resp.headers.get("Retry-After")
retry_after = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
)
if resp.status_code in (429, 503):
time.sleep(retry_after)
continue
if resp.status_code >= 500: # 500, 502, 503, 504 are all ours to fix
time.sleep(2 ** attempt)
continue
# 400/401/403/404 won't fix themselves
raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")
raise RuntimeError(f"Exhausted {max_retries} retries")
代理失败包含报告
耗尽尝试次数的 POST /api/proxy/ 调用会以包含错误封包的 HTTP 200 返回,而不是 HTTP 错误代码。错误字符串很短且格式固定,因此随附一个包含计数信息的 attemptReport 对象:
{
"error": "Download maxTry limit reached",
"attemptReport": {
"total": 25,
"noResponse": 0,
"defense": 0,
"contentRejected": 25,
"statusRejected": 0,
"other": 0,
"vendors": [],
"profilesTried": ["default"],
"summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
},
"total": 34.812
}
在错误旁记录 attemptReport.summary,您就能明确出口是被阻止、失效,还是返回了被您自定义 validate 规则拒绝的页面。字段参考及针对各项计数的应对措施:代理请求耗尽重试次数的原因。