如何处理来自 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 规则拒绝的页面。字段参考及针对各项计数的应对措施:代理请求耗尽重试次数的原因。

更新于: 2026年11月13日