跨请求重用代理

了解如何在后续 request 中保持相同的 proxy 出口，从而使 JavaScript 渲染、API 调用和分页抓取均来自同一个 IP。

为何复用 Proxy

首次访问目标时，FourA 会为你选择一个可用的 proxy。每个 response 都会包含其使用的 proxy ID。在后续 request 中传回该 ID 即可：

后续页面通过相同的出口访问，从而使 session cookie 和 rate limit 对目标保持一致。
限定国家/地区的抓取会保留在你的 allowlist 内，无需重新选择。
低成本的 POST /api/single/ endpoint 可通过你已付费发现的 proxy 重放，仅消耗 Single 的费用而非 Proxy 的费用。

Proxy ID 是一个不透明的 base36 字符串（类似于 A1B2C3）。绝非原始 IP。

ID 在 Response 中的位置

Endpoint	字段	出现时机
`POST /api/auto/`	`session.proxy`	当 `returnSession` 为 `true`（默认值）时
`POST /api/single/`	`proxy`（顶层）	仅当 request 提供了 `proxy` 字段时
`POST /api/proxy/`	`proxy`（顶层）	成功时始终存在
`POST /api/browser/`	`proxy`（顶层）	仅当 request 提供了 `proxy` 字段时

如需获取全新的出口而不固定出口，请从 Auto 或 Proxy 开始。两者都会发现可用的出口并为你返回其 ID。

模式 1：Auto 发现，Single 重放

适用于尚不熟悉的目标。Auto 会遍历一次梯级，随后 Single 会为每个后续页面复用成功的 session。

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# Step 1: discover a working exit with Auto.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# Step 2: paginate with Single, reusing the same exit and User-Agent.
for sku in ("43", "44", "45"):
    p = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, p["status"])

Auto 调用的费用取决于其梯度阶段的实际消耗。后续的每次 Single 调用消耗 2 个积分（默认带 unblocker 的 Single）。

模式 2：Proxy 发现，Browser 通过相同出口节点渲染

当目标站点必须识别特定出口国家且最终内容需要 JavaScript 时使用此模式。

# Step 1: pick a country-scoped exit with Proxy.
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,
    "exitCountries": ["FR", "GB"],
    "request": {"method": "GET", "url": "https://example.com/pricing"}
  }'
# Response includes: "proxy": "A1B2C3", "exitCountry": "FR"

# Step 2: render the JS-heavy page through THAT exit.
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/pricing",
    "proxy": "A1B2C3",
    "timeout_ms": 20000
  }'

请勿再次调用 /api/proxy/ 来刷新选择。新的调用可能会选择不同的出口，从而失去固定的意义。如果已固定的出口停止工作，请运行新的 /api/proxy/ 调用以选择新出口，然后继续使用该出口。

模式 3：跳过已失效的出口

如果之前正常工作的出口开始返回拒绝响应或验证页面，请指示 FourA 在下次选择时避开该出口。

{
  "maxTries": 5,
  "ignoreProxies": ["A1B2C3"],
  "request": { "method": "GET", "url": "https://example.com/data" }
}

ignoreProxies 接收早期响应返回的 proxy ID 列表。它适用于 /api/proxy/ 和 /api/auto/。该列表在每次内部重试时均有效，因此带有 ignoreProxies 的单次调用绝不会选择已失效的出口。

固定会话的有效期

出口本身的存活时间取决于底层 proxy 的健康状态，通常为几分钟到几小时不等。如果重放请求开始返回验证质询、拦截或非预期的重定向，则该出口可能已被轮换，或目标站点刷新了其放行凭证。

发生这种情况时的两种选择：

针对相同 URL 发起全新的 /api/auto/ 调用。Auto 将发现新的可用会话；废弃之前的 ID。
如果您希望继续手动固定，发起带有 ignoreProxies: ["<burned-id>"] 的全新 /api/proxy/ 调用。

Auto 响应中的 Session cookie 也会根据目标站点的规则过期。某些站点会将放行状态绑定数小时；其他站点则仅维持数分钟。请将该会话视为缓存，而非持久 token。

当 ID 无法固定时

proxy 值可能会返回三种 400 错误，它们代表不同的含义：

错误	发生原因	解决办法
`Invalid proxy format`	该值不是 FourA 签发的 ID。直接传入原始 proxy 地址会导致此错误。	逐字发送响应中返回的不透明字符串。
`Proxy not found`	ID 已成功解码，但不再解析为活跃的出口。	从新的 Auto 或 Proxy 调用中获取全新的出口。
`Managed exit: this proxy id cannot be pinned to a request`	该 ID 属于高级出口，且您当前周期的套餐高级流量已用尽，或您的套餐不包含高级出口。	通过 `POST /api/proxy/` 运行调用并接受其选择的出口，或者增加高级流量配额后重新固定。

第三种错误来自成功调用返回给您的 ID，因此即使操作完全正确也可能遇到。请像处理过期会话一样对待它：回退到全新的发现调用，而不是重试相同的 ID。

常见错误

**跨账户复用 proxy ID。**切勿在账户之间共享 ID：一个账户可以固定的 ID 可能会被另一个账户拒绝，例如在没有高级流量的套餐中使用高级出口。
**尝试解码 ID。**Base36 字符串是不透明的。请勿解析、去除字符或将其转换为小写。请原样传回。
**通过受 rate limit 限制的出口进行固定。**如果目标对每个 IP 进行 rate limit，通过单个出口汇聚大量 requests 会更快触发封禁。对于高并发负载，让 Auto 或 Proxy 在多个出口之间轮换，仅在目标确实需要时才进行固定。
**无意中固定了高级出口。**由高级出口提供服务的调用所返回的 ID（Proxy 上的 exitClass: "premium"）会固定该高级出口。通过它的每次重放都会计入您的高级流量，且 response 会携带 X-FourA-Exit-Class: premium。
**在不支持地理定位的套餐上发送 exitCountries。**国家/地区范围划分包含在 Startup 及以上套餐中。在不支持该功能的套餐上，发送 exitCountries 的调用将被拒绝，并返回 403 和 X-FourA-Limit: plan_limit_feature。
**在后续调用中忽略 exitCountries。**如果您固定了一个限定范围的出口，然后再次调用 Proxy 时未携带 exitCountries，后续调用可能会通过不同的国家/地区发出。请在每个需要它的调用中保留该范围配置。