# 常见问题

> URL: https://foura.ai/zh/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

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

## 内容为空或不完整

**症状：** API 返回 200 状态码，但 `data` 字段为空或缺少预期内容。

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

**解决方案：** 从单 endpoint 切换到 browser endpoint。使用 `checkText` 验证内容是否已加载：

```bash
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 轮换：

```bash
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](#403-not-in-your-plan)。

## 超时错误

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

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

**解决方案：** 调大 `timeout_ms`（默认单次 request 为 15s，browser 为 30s，proxy 为 45s）：

```bash
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`。

```json
{
  "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`，以及在高级流量耗尽后指定 [出口位置](https://foura.ai/docs/api/endpoints#exit-location) 的 Proxy 请求。目标未被访问，也没有产生扣费。

**解决方案：** 移除该参数、调用套餐内包含的 endpoint，或升级套餐。[用量与限额](https://foura.ai/docs/dashboard/quota) 的 **限额与功能** 标签页列出了您套餐包含的内容。请勿原样重试：由于等待不会改变结果，因此未设置 `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` 中：

```python
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](https://foura.ai/docs/how-to/run-requests-in-parallel) 提供了相应模式，[Dashboard](https://foura.ai/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` 秒，然后重试：

```python
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` 加上一个较小的缓冲时间，因此调高该值确实会延长等待时间：

```json
{
  "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` 计费，因此重试无需额外费用。如果持续超过一两分钟，请查看 [状态页](https://updates.foura.ai/status)。

## 401 身份验证错误

**症状：** 每个 request 均返回 401 Unauthorized。

**排查清单：**
1. 验证 header 是否为 `X-API-Key: YOUR_API_KEY`（而非 `Authorization: Bearer` 或 `Api-Key`）
2. 检查 API key 中是否存在多余的空格或换行符
3. 如果当前密钥可能已泄露，请从 [控制面板](https://foura.ai/dashboard)创建新密钥

## 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 参考](https://foura.ai/docs/api/endpoints)列出了每个字段及其类型和限制。在 `/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`。如果您的目标是您自身运行的服务，请先将其暴露在公开主机名上。

```json
{ "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](https://foura.ai/docs/api/inspect) (`/inspect`) 是 API 主机上唯一可以通过 FourA 抓取的地址。

## 使用 exitCountries 时出现 no_eligible_proxy

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

```json
{
  "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` 结束。

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

```python
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`](https://foura.ai/docs/api/endpoints#browser-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>]}` 返回，不执行任何字符集转码。

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

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

## 意外收到 HTML 而非 JSON

**症状：** 预期从目标网站获取 JSON，但实际收到了 HTML。

**原因：** 目标页面可能会根据请求 header 返回不同的内容。

**解决方案：** 添加 `Accept` header 并启用 `unblocker` 以生成真实的浏览器 header：

```bash
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。完整字段参考与供应商列表请参阅 [站点验证](https://foura.ai/docs/api/site-checks)。

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

## 仍未解决？

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

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

## 后续步骤

- [错误处理](https://foura.ai/docs/api/errors)：API 错误代码参考
- [速率限制](https://foura.ai/docs/api/rate-limits)：包含详细字段的各套餐限制与平台限制说明
- [请求结果](https://foura.ai/docs/api/outcomes)：结果分类机制说明
- [站点验证](https://foura.ai/docs/api/site-checks)：`defense` 字段的详细说明
- [选择合适的端点](https://foura.ai/docs/guides/choosing-task-type)：根据目标选择最佳方案
- [控制台概览](https://foura.ai/docs/dashboard/overview)：监控你的请求
