> 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-chu.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 多次重试后仍请求失败` | 所有上游引擎都失败了。未收费。                                                  | 是，使用退避。                                                          |
| `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 个请求字段无效；修正 `errors` 中的每一项并重新发送。",
  "instance": "6285041d-b00d8d69959c4b36f50fb53b",
  "metadata": {
    "timestamp": 1788762578,
    "request_id": "1788875675880097469"
  },
  "errors": [
    {
      "pointer": "#/max_results",
      "detail": "输入值应小于或等于 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>状态</code></td><td>仅在故障响应中存在（ <code>500</code> 响应中（<code>"faulted"</code>）。成功调用返回 <code>"done"</code>.</td><td>字符串</td></tr><tr><td><code>标题</code></td><td>机器可读的错误代码。应用逻辑应根据此字段分支处理。</td><td>字符串</td></tr><tr><td><code>详情</code></td><td>人类可读的错误说明。不要匹配这段说明文本。</td><td>字符串</td></tr><tr><td><code>实例</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 纪元时间戳（秒）。</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())  # 抖动可避免同步重试
```

在持续的 `429`情况下，降低并发而不是缩短退避。更快地重试无法解决速率限制。

## 常见错误与解决方案

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

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

**解决方案：** 如果 HTTP `429` 在超过 30 秒的多次退避尝试后仍持续存在，则你的账户已耗尽每月请求配额。请检查 [Oxylabs Dashboard](https://dashboard.oxylabs.io).

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

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

**解决方案：** 将客户端超时设置为约 150 秒。对于任何可能长时间运行的请求，请使用 [Async Delivery](/products/cn/web-api/scrape/jiao-fu-mo-shi.md#single-job-delivery-async) 来代替保持连接打开。

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

`/media` 及其子端点任务可能会以 HTTP `200` 和 `状态："done"`结束，但在 `results[0].metadata.statuses.video_download`:

{% code expandable="true" %}

```json
"statuses": {
    "video_download": {
        "code": 11206,
        "tag": "DOWNLOAD_FAILED_VIDEO_AGE_RESTRICTED", //"DOWNLOAD_FAILED_" 前缀 + 状态
        "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-chu.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.