# API 错误

> URL: https://foura.ai/zh/docs/api/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

如何处理来自 FourA API 的错误。

## 错误响应格式

API 对所有错误均返回扁平的 JSON 对象。不存在嵌套的 `error` 对象。若失败包含机器可读的代码，它将作为顶层字段呈现：超出方案配额限制时为 `reason`，proxy 调用没有符合条件的出口时为 `code`。

```json
{
  "error": "Invalid API key"
}
```

部分错误在顶层包含额外字段，例如 `status`、`service`、`retryAfter`、`current` 或 `limits`：

```json
{
  "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 能帮助我们定位该请求。

```bash
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` 结束：

```json
{
  "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 网络之前被拒绝：

```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."
}
```

`<target>` 是地址，或者是主机名及其解析出的地址。无法解析的 URL，或不是 `http://` 或 `https://` 的 URL，同样会返回 400。

在 Single、Proxy Finder、Browser 和 Auto 模式下，针对 FourA 自身 API 主机（`eu.api.foura.ai` 或 `api.foura.ai`）的目标也会在抓取或扣费之前返回 400。这通常意味着从页面提取的链接被错误解析到了 API URL 而非页面自身的 URL：

```json
{
  "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](https://foura.ai/docs/api/inspect) 页面是唯一的例外：FourA 仍会为您抓取 `https://eu.api.foura.ai/inspect`。

包含空格或控制字符的 URL 在 Single、Proxy Finder 和 Auto 上也会返回 400，且在发起抓取或计费之前就会拦截。直接从页面复制的链接通常包含这些字符（`javascript: void(0)`，文本中带有空格的分享链接）。请对其进行编码，将空格转义为 `%20`。Browser 会像 Chrome 一样抓取此类 URL：

```json
{
  "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`：参见 [请求结果](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like)。

在 Single 上，解码后超过 128 MB 的 response body 会在此截断。该调用返回 HTTP 200，带有 `"error": "Response body exceeds the 128 MB limit"`，且不计费。

body 中格式错误的 JSON 会在读取任何字段前以相同方式被拒绝：

```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：

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

无效密钥:

```json
{
  "error": "Invalid API key"
}
```

**解决方法：**验证您的 `X-API-Key` header 包含有效 key。如有需要，可从 [控制台](https://foura.ai/dashboard)生成新 key。

401 始终表示 FourA 已校验您的 key 并拒绝了请求。当 FourA 在数秒内无法校验 key 时，将返回 503 `API key check temporarily unavailable`（见下文），绝不会返回 401。

### 403: 未包含在您的方案中

调用请求了当前方案未包含的 endpoint 或参数。响应会设置 `X-FourA-Limit`，并在响应体中的 `reason` 字段返回相同的代码：

```json
{
  "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](https://foura.ai/docs/api/endpoints#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` 字段提供相同的代码：

```json
{
  "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` 中：

```json
{
  "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` 对应的时间。若遇到并发或速率限制，请限制保持打开的请求数量，而不是重新发送被拒绝的批次。若遇到每日或计费周期限制，请停止运行。有关各字段的详细信息，请参阅 [速率限制](https://foura.ai/docs/api/rate-limits)；有关实现模式，请参阅 [并行运行请求](https://foura.ai/docs/how-to/run-requests-in-parallel)。

### 500: 服务器错误

我们服务端出现异常。

**解决方法：** 稍后重试请求。如果错误仍然存在，请查看 [状态页](https://updates.foura.ai/status)，或附带失败响应中的 `X-FourA-Request-Id` 联系支持团队。

### 502: 上游不可用

FourA 无法从自身引擎获取响应（`Upstream unavailable`：连接失败），或者收到了无法读取的响应（`Malformed JSON from backend`）。

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**解决办法：**稍后重试（短退避时间）。这是我们端的问题，因此不收取任何费用：结果为 `service_error`，并且仅对 `success` 计费。

### 504: 上游超时

引擎未能在该请求的时间预算内完成。

```json
{
  "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` 字符串进行区分，而不是根据包含哪些字段。

```json
{
  "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](https://foura.ai/docs/api/rate-limits)。

**解决方法：** 等待 `retryAfter` 秒，然后重试。状态页面列出了当前生效的维护时间窗口。

第三种 503 格式不包含 `retryAfter`。这意味着您 endpoint 背后的引擎无法接收调用：它可能正在重启、在您的 request 运行之前已在 FourA 侧发生故障，或者（在 Browser 上）在页面等待的 10 秒内所有浏览器实例均处于繁忙状态。`backend_status` 是引擎自身的状态，`detail` 是其响应的开头部分：

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}
```

这是 `service_error`，且不计费。请在一两秒后重试。本身有误的 request 绝不会进入此状态：它会返回明确指出具体字段的 400 错误。

第四种 503 表示 FourA 暂时无法确认您的 API key，例如在数据库切换期间。您的 key 没有问题，且没有执行任何操作。它带有 `Retry-After: 5` 以及在 `retryAfter` 中相同的等待时间：

```json
{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}
```

该情况不计费。请在 `retryAfter` 秒后重试。FourA 在过去 10 分钟内确认过的 key 在此期间会继续有效，因此该响应很少出现。

## 从 `/api/auto/` 读取失败信息

只要阶梯策略已执行，即使每个阶梯环节均失败，`POST /api/auto/` 也会返回 HTTP 200。实际结果位于 body 中：

```json
{
  "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 调用失败的原因](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed)。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：

```json
{
  "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)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder)。

## 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](https://foura.ai/docs/api/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>]}`），而不应用任何字符集转码。

## 重试策略

实用的重试策略：

```python
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` 对象：

```json
{
  "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` 规则拒绝的页面。字段参考及针对各项计数的应对措施：[代理请求耗尽重试次数的原因](https://foura.ai/docs/troubleshooting/proxy-attempt-report)。

## 相关内容

- [速率限制](https://foura.ai/docs/api/rate-limits)：套餐限制、并发与 RPM 详情
- [并行运行请求](https://foura.ai/docs/how-to/run-requests-in-parallel)：保持在套餐并发限制之内
- [请求结果](https://foura.ai/docs/api/outcomes)：七种结果值详解
- [常见问题](https://foura.ai/docs/troubleshooting/common-issues)：症状、原因与修复方案
- [站点检查](https://foura.ai/docs/api/site-checks)：当响应体为质询页面而非错误时
- [代理请求耗尽重试次数的原因](https://foura.ai/docs/troubleshooting/proxy-attempt-report)：解读 `attemptReport`
