> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-api/gu-zhang-pai-cha.md).

# 故障排查

Web API 状态码、错误响应格式、重试策略和常见故障排除方案。

## 状态码

| 状态 + 代码                                     | 说明                                                                 | 重试？                                                                |
| ------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `200 OK`                                    | 响应体中的 Realtime 结果                                                  | –                                                                  |
| `202 已接受`                                   | 异步任务已接受                                                            | –                                                                  |
| `400 请求体格式错误`                               | 请求体不是有效的 JSON                                                      | 不，修正负载格式。                                                          |
| `400 验证错误`                                  | 一个或多个字段验证失败。                                                       | 不，修正所有条目 `errors[]` 后再重新发送。                                        |
| `401 未授权`                                   | 认证错误（缺少、无效、格式错误或已撤销的密钥）。此状态下没有响应体。                                 | 不，修正凭据。                                                            |
| `404 未找到`                                   | 在以下路径下的路径 `/search` 不存在，或者异步 `request_id` 不存在或已过期。                 | 否                                                                  |
| `405 方法不允许`                                 | 使用了错误的 HTTP 方法（端点要求 `POST`).                                       | 否                                                                  |
| `408 请求超时`                                  | `/scrape` 仅限。采集器未在服务器等待窗口内响应                                       | 是，使用退避重试。                                                          |
| `429 请求过多`                                  | 已达到速率限制或配额上限。参见 [常见错误](#id-1.-rate-limit-vs.-quota-exhaustion-429) | <p><strong>速率限制：</strong> 是，使用退避重试。<br><strong>配额：</strong> 否。</p> |
| `500 REQUEST_FAILED_AFTER_TOO_MANY_RETRIES` | 所有上游引擎均失败。未计费。                                                     | 是，使用退避重试。                                                          |
| `500 服务器内部错误`                               | 意外的系统故障                                                            | 是，使用退避重试。                                                          |
| `503 服务不可用`                                 | 上游服务暂时不可用                                                          | 是，使用退避重试。                                                          |
| `5xx`                                       | 其他临时性上游故障                                                          | 是，最多退避重试约 3 次。                                                     |

{% hint style="info" %}

* `代码` 值特定于 `/search` 结构化错误体（见下文）。其他端点只返回状态码。
* 随着 API 增长，可能会出现新代码：将无法识别的代码视为“此状态类别的错误”。
  {% endhint %}

## 错误响应

`/search` 失败使用一个 [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 问题文档，格式为 `application/problem+json`:

```json
{
  "status": 400,
  "title": "VALIDATION_ERROR",
  "detail": "1 request field is invalid; fix every entry in `errors` and resend.",
  "instance": "6285041d-b00d8d69959c4b36f50fb53b",
  "metadata": {
    "timestamp": 1788762578,
    "request_id": "1788875675880097469"
  },
  "errors": [
    {
      "pointer": "#/max_results",
      "detail": "Input should be less than or equal to 20"
    }
  ]
}
```

<table><thead><tr><th width="195">字段</th><th>说明</th><th width="111">类型</th></tr></thead><tbody><tr><td><code>status</code></td><td>与响应状态行匹配的 HTTP 状态码。</td><td>数字</td></tr><tr><td><code>state</code></td><td>出现在故障 <code>500</code> 响应（<code>"faulted"</code>）。成功调用返回 <code>"done"</code>.</td><td>字符串</td></tr><tr><td><code>title</code></td><td>机器可读错误代码。应用逻辑应基于此字段分支。</td><td>字符串</td></tr><tr><td><code>detail</code></td><td>错误的人类可读说明。不要依据这段说明文本进行匹配。</td><td>字符串</td></tr><tr><td><code>instance</code></td><td>请求的跟踪标识符。请在支持咨询中包含它。</td><td>字符串</td></tr><tr><td><code>metadata.request_id</code></td><td>用于跟踪和支持的 19 位请求句柄。</td><td>字符串</td></tr><tr><td><code>metadata.timestamp</code></td><td>以秒为单位的 Unix epoch 时间戳。</td><td>数字</td></tr><tr><td><code>params</code></td><td>请求中使用的所有参数及已应用的默认值。出现在已验证的请求中（例如， <code>500</code>），不出现在 <code>400</code>.</td><td>对象</td></tr><tr><td><code>errors[]</code></td><td>参数失败列表。出现在 <code>VALIDATION_ERROR</code> 仅。</td><td>数组</td></tr><tr><td><code>errors[].pointer</code></td><td>用于标识被拒绝字段的 JSON Pointer（例如， <code>#/max_results</code>).</td><td>字符串</td></tr><tr><td><code>errors[].detail</code></td><td>说明该特定字段被拒绝的原因。</td><td>字符串</td></tr></tbody></table>

## 重试

重试 `408`, `429`，以及 `5xx` 使用指数退避和抖动重试，最多约 3 次：

```python
import random, time, requests

RETRYABLE = {408, 429, 500, 502, 503, 504}

def call(url, payload, headers, attempts=3):
    for attempt in range(1, attempts + 1):
        try:
            resp = requests.post(url, json=payload, headers=headers, timeout=120)
        except requests.Timeout:
            if attempt == attempts:
                raise
            time.sleep(2**attempt + random.random())
            continue
        if resp.ok:
            return resp.json()
        if resp.status_code not in RETRYABLE or attempt == attempts:
            raise RuntimeError(f"{resp.status_code}: {resp.text[:200]}")
        time.sleep(2**attempt + random.random())  # jitter avoids lockstep retries
```

在持续 `429`，降低并发，而不是缩短退避。针对速率限制更快地重试不会解决问题。

## 常见错误与解决方案

### **1. 速率限制与配额耗尽（`429`)**

速率限制违规（超过每秒请求并发数）和账户配额耗尽都会返回一个 HTTP `429 Too Many Requests` 状态码。

**解决方案：** 如果某个 HTTP `429` 在超过 30 秒的多次退避重试后仍然持续出现，则表示你的账户已耗尽每月请求配额。请在以下位置检查你的当前使用限制： [Oxylabs 仪表板](https://dashboard.oxylabs.io).

### **2. JavaScript 密集型页面超时（`run_js: true`)**

无头浏览器渲染（`run_js: true`）或复杂目标站点所需的处理时间远高于标准 HTML 获取，通常超过典型的默认客户端超时（5–10 秒）。

**解决方案：** 将客户端超时设置为约 150 秒。对于无论如何都可能运行较久的任务，使用 [Async Delivery](https://developers.oxylabs.io/products/cn/web-api/scrape/jiao-fu-mo-shi.md#single-job-delivery-async) ，而不是保持连接打开。

## 媒体特定错误（`/scrape/media`)

`/media` 及其子端点任务可能以 HTTP `200` 和 `state: "done"`结束，但在以下位置返回没有数据或文件，并带有媒体特定错误： `results[0].metadata.statuses.video_download`:

{% code expandable="true" %}

```json
"statuses": {
    "video_download": {
        "code": 11206,
        "tag": "DOWNLOAD_FAILED_VIDEO_AGE_RESTRICTED", //"DOWNLOAD_FAILED_" prefix + status
        "details": "The video is age-restricted."
    }
}
```

{% endcode %}

{% hint style="info" %}
`11201`-`11211` 适用于 `/media/youtube/metadata`, `/media/youtube/subtitles` 和 `/media/youtube/download` 仅限端点。
{% endhint %}

<table><thead><tr><th width="219">错误</th><th width="271">说明</th><th>解决方案</th></tr></thead><tbody><tr><td><code>11201</code><br><code>VIDEO_DELETED</code></td><td>该 YouTube 视频已被删除。</td><td>在浏览器中打开 URL 以确认视频仍然存在。重试同一个视频不会有帮助。</td></tr><tr><td><code>11202</code><br><code>VIDEO_UNAVAILABLE</code></td><td>YouTube 报告该视频不可用。</td><td>在浏览器中打开视频以检查是否可以播放。如果可以，请联系支持并提供任务的 <code>request_id</code>.</td></tr><tr><td><code>11203</code><br><code>VIDEO_PRIVATE</code></td><td>上传者将视频设为私密，因此只有他们和受邀观众可以观看。</td><td>请使用公开视频。</td></tr><tr><td><code>11204</code><br><code>VIDEO_GEO_RESTRICTED</code></td><td>该视频在任务运行所在地区不可用。</td><td>如果你需要该视频，请联系支持并提供任务的 <code>request_id</code>.</td></tr><tr><td><code>11205</code><br><code>VIDEO_LIVE</code></td><td>该视频正在直播。</td><td>在直播结束后重试。</td></tr><tr><td><code>11206</code><br><code>VIDEO_AGE_RESTRICTED</code></td><td>该视频有年龄限制。</td><td>有年龄限制的视频无法获取。请使用其他视频。</td></tr><tr><td><code>11207</code><br><code>VIDEO_MEMBER_ONLY</code></td><td>该视频仅对付费频道会员开放。</td><td>仅会员可观看的视频无法获取。请使用其他视频。</td></tr><tr><td><code>11208</code><br><code>VIDEO_PREMIUM_ONLY</code></td><td>该视频需要 YouTube Premium 订阅。</td><td>仅限 Premium 的视频无法获取。请使用其他视频。</td></tr><tr><td><code>11209</code><br><code>VIDEO_LIVE_OR_TOO_LONG</code></td><td>该视频要么正在直播，要么过长，无法下载。 <code>/media/youtube/download</code> 仅。</td><td>如果视频正在直播，请在直播结束后重试。最长 12 小时的视频可以下载。</td></tr><tr><td><code>11210</code><br><code>VIDEO_TOO_LONG</code></td><td>该视频过长，无法下载。 <code>/media/youtube/download</code> 仅。</td><td>最长 12 小时的视频可以下载。请使用更短的视频。</td></tr><tr><td><code>11211</code><br><code>VIDEO_SIGN_IN_REQUIRED</code></td><td>查看该视频需要登录 YouTube。 <code>/media/youtube/download</code> 仅。</td><td>需要登录才能观看的视频无法下载。请使用其他视频。</td></tr><tr><td><code>11301</code><br><code>MEDIA_UNAVAILABLE</code></td><td>该视频已被删除，或者其所属帖子已不再存在。</td><td>在浏览器中打开 URL 以确认视频仍然存在。重试同一个 URL 不会有帮助。</td></tr><tr><td><code>11302</code><br><code>MEDIA_PRIVATE</code></td><td>该视频或发布它的账户是私密的。只能下载公开视频。</td><td>请使用公开视频的 URL。</td></tr><tr><td><code>11303</code><br><code>MEDIA_GEO_RESTRICTE</code>D</td><td>该视频在任务所在地区不可用。 <code>/media</code> 端点没有 <code>location</code> 参数，因此无法在请求中更改地区。</td><td>如果你需要该视频，请联系支持并提供任务的 <code>request_id</code>.</td></tr><tr><td><code>11304</code><br><code>MEDIA_UNSUPPORTED</code></td><td>URL 中未找到视频：可能是照片或幻灯片帖子、直播、无视频的帖子，或过长/过大的视频，无法下载。</td><td>检查 URL 是否匹配接受的 URL 格式之一，并指向单个录制视频。</td></tr><tr><td>视频未到达你的 bucket</td><td><code>storage.url</code> 未经过验证。拼写错误的 bucket 或路径也会被接受，任务会运行并计费，但上传会失败。</td><td>检查 <code>storage.type</code> 和 <code>storage.url</code> 发送前。对于 <code>s3_compatible</code> 和 <code>tos</code>, <code>storage.url</code> 必须是带凭据的完整 URL，例如 <code>https://key:secret@host/bucket/path</code>.</td></tr></tbody></table>

## 报告问题

如果 API 问题持续存在，请在向以下支持提交工单之前，从响应载荷中获取唯一请求句柄： [Oxylabs Technical Support](mailto:support@oxylabs.io).

* **响应字段：** `metadata.request_id` （例如， `"1788875675880097469"`)
* **网关错误字段：** `trace_id` （例如， `"d940ba3c-2109-4391-a292-9f2c0613a656"`)

包含 `request_id` 或 `trace_id` 可让我们的支持团队立即定位任务、代理节点路由数据和上游响应代码。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-api/gu-zhang-pai-cha.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
