> 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/api-reference/cn/cuo-wu-yu-zhuang-tai-ma.md).

# 错误与状态码

HTTP 状态码、RFC 9457 问题文档、错误分类以及 Oxylabs Web API 生产重试逻辑的技术规范。

### 状态码与重试矩阵

重试逻辑必须严格基于响应的 HTTP 状态码。对不可重试的客户端错误进行重试（`400`, `401`, `403`, `404`)会导致相同的失败和不必要的 API 负载。

<table><thead><tr><th width="207">状态 + 代码</th><th width="183">RFC 9457 标题</th><th>描述</th><th width="117">可重试？</th></tr></thead><tbody><tr><td><code>200 OK</code></td><td>—</td><td>Realtime 调用成功。执行完成；处理响应正文。</td><td>否</td></tr><tr><td><code>202 已接受</code></td><td>—</td><td>异步作业已接受。作业已排队；通过以下方式获取： <code>metadata.request_id</code>.</td><td>否</td></tr><tr><td><code>400 错误请求</code></td><td><code>INVALID_BODY_PROPERTY</code>, <code>MALFORMED_JSON</code></td><td>验证失败或负载格式错误。请修正以下内容中的参数： <code>errors[]</code> 后再重新发送。</td><td>否</td></tr><tr><td><code>401 未授权</code></td><td>— <em>(空正文)</em></td><td>API 密钥无效、缺失或已吊销。请验证 Bearer 令牌格式和 dashboard 实例密钥。</td><td>否</td></tr><tr><td><code>403 禁止访问</code></td><td>—</td><td>权限限制。账户无法访问目标路由或源。</td><td>否</td></tr><tr><td><code>404 未找到</code></td><td><code>NOT_FOUND</code></td><td>路由或作业 ID 无效/已过期。请检查端点路径或异步请求句柄。</td><td>否</td></tr><tr><td><code>405 方法不允许</code></td><td><code>METHOD_NOT_ALLOWED</code></td><td>除以下方法外的其他方法： <code>POST</code> 已使用。将 HTTP 请求方法更改为 <code>POST</code>.</td><td>否</td></tr><tr><td><code>408 请求超时</code></td><td>—</td><td>Realtime 抓取超时。使用指数退避重试请求。</td><td>是</td></tr><tr><td><code>413 负载过大</code></td><td>—</td><td>负载或批处理大小超出限制。请减小负载大小或批处理目标数量。</td><td>否</td></tr><tr><td><code>429 请求过多</code></td><td>—</td><td>并发限制或配额已耗尽。降低并发并应用带抖动的退避。如果持续存在，请提醒操作员。</td><td><p>速率限制：是</p><p>配额：否</p></td></tr><tr><td><code>500 内部错误</code></td><td><code>REQUEST_FAILED_AFTER_TOO_MANY_RETRIES</code>, <code>INTERNAL_ERROR</code></td><td>上游故障或抓取失败。失败的抓取不计费。使用退避重试。</td><td>是</td></tr><tr><td><code>503 服务不可用</code></td><td><code>SERVICE_UNAVAILABLE</code></td><td>服务暂时不可用。使用退避重试。</td><td>是</td></tr></tbody></table>

### RFC 9457 问题文档

当发生 HTTP 错误时，Web API 会返回一个 [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 问题文档，其格式为 `application/problem+json`.

{% hint style="info" %}
`401 未授权` 例外：HTTP `401` 状态响应携带空正文。HTTP 状态码本身表示完整的认证失败状态。
{% endhint %}

#### 1. 无效的正文属性（`400 错误请求`)

无效的 `storage.url` 返回 `VALIDATION_ERROR` 并附带 `errors[].pointer` 设置为 `#/storage/url`。请求不会被创建。

```json
{
  "status": 400,
  "title": "INVALID_BODY_PROPERTY",
  "detail": "正文属性的值无效。",
  "instance": "6ad5c6df-4ef52bbe9bd1519f8dbfc4ae",
  "errors": [
    {
      "detail": "必须是以下之一：gcs, s3, s3_gzip, s3_compatible, tos。",
      "pointer": "#/storage/type"
    }
  ]
}
```

#### 2. 抓取失败错误（`500 内部错误`)

如果抓取在所有重试后仍失败， `POST /v1/scrape` 将返回 HTTP `500` 状态，并带有 `state: "faulted"`。失败的抓取不消耗账户配额。

```json
{
  "status": 500,
  "state": "faulted",
  "title": "REQUEST_FAILED_AFTER_TOO_MANY_RETRIES",
  "detail": "请求在达到最大重试次数后失败。你可以再次尝试，不会产生额外费用，因为失败的抓取不收费。",
  "instance": "6ad5c789-3cb04e139b34a1eaee352bae",
  "params": {
    "url": "https://oxyasdasdasdasdlabsghrehaerhaerh.io",
    "output": ["html"],
    "json": { "schema": null, "prompt": null },
    "location": null,
    "device": "desktop",
    "run_js": null
  },
  "metadata": {
    "timestamp": 1792395145,
    "request_id": "7517850129655711745"
  }
}
```

### 响应模式解析

<table><thead><tr><th width="192">字段路径</th><th width="99.5">类型</th><th>描述</th></tr></thead><tbody><tr><td><code>status</code></td><td>整数</td><td>HTTP 状态码。</td></tr><tr><td><code>state</code></td><td>字符串</td><td>出现在 faulted 抓取响应中（ <code>500</code> 抓取响应中（<code>"faulted"</code>）。成功调用返回 <code>"done"</code>.</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>字符串</td><td>用于计费和支持工单的 19 位跟踪句柄。</td></tr><tr><td><code>metadata.timestamp</code></td><td>整数</td><td>以秒为单位的 Unix 时间戳。</td></tr><tr><td><code>errors[]</code></td><td>数组</td><td>出现在请求验证错误中。包含字段级失败对象。</td></tr><tr><td><code>errors[].pointer</code></td><td>字符串</td><td>标识无效请求字段的 JSON Pointer（例如， <code>#/storage/type</code>).</td></tr><tr><td><code>errors[].detail</code></td><td>字符串</td><td>指定字段指针的详细失败原因。</td></tr></tbody></table>

### 错误代码参考（`title`)

程序化错误路由应评估 `title` 属性：

<table><thead><tr><th>"title" 代码</th><th width="122">HTTP 状态</th><th>描述</th></tr></thead><tbody><tr><td><code>MALFORMED_JSON</code></td><td><code>400</code></td><td>请求正文不是有效的 JSON。</td></tr><tr><td><code>INVALID_BODY_PROPERTY</code></td><td><code>400</code></td><td>请求正文属性的值无效。</td></tr><tr><td><code>NOT_FOUND</code></td><td><code>404</code></td><td>路由路径无效或端点子资源未分配。</td></tr><tr><td><code>METHOD_NOT_ALLOWED</code></td><td><code>405</code></td><td>使用了错误的 HTTP 方法（Web API 端点要求 <code>POST</code>).</td></tr><tr><td><code>REQUEST_FAILED_AFTER_TOO_MANY_RETRIES</code></td><td><code>500</code></td><td>抓取在达到最大重试次数后失败。不收费。</td></tr><tr><td><code>INTERNAL_ERROR</code></td><td><code>500</code></td><td>内部处理错误。</td></tr><tr><td><code>SERVICE_UNAVAILABLE</code></td><td><code>503</code></td><td>后端服务临时中断。</td></tr></tbody></table>

### 媒体特定错误

由以下项返回 `POST /v1/async/scrape/media` 及其子端点在视频无法下载时返回。

<table><thead><tr><th width="74.03125">代码</th><th width="216.372304199773">状态</th><th>描述</th></tr></thead><tbody><tr><td><code>11201</code></td><td><code>VIDEO_DELETED</code></td><td>视频已删除。</td></tr><tr><td><code>11202</code></td><td><code>VIDEO_UNAVAILABLE</code></td><td>视频不可用。</td></tr><tr><td><code>11203</code></td><td><code>VIDEO_PRIVATE</code></td><td>视频已由上传者设为私密，只有上传者本人和明确受邀的人可以查看。</td></tr><tr><td><code>11204</code></td><td><code>VIDEO_GEO_RESTRICTED</code></td><td>视频受地域限制。</td></tr><tr><td><code>11205</code></td><td><code>VIDEO_LIVE</code></td><td>视频当前正在直播。</td></tr><tr><td><code>11206</code></td><td><code>VIDEO_AGE_RESTRICTED</code></td><td>视频受年龄限制。</td></tr><tr><td><code>11207</code></td><td><code>VIDEO_MEMBER_ONLY</code></td><td>视频仅供频道会员观看，观众需要支付月度订阅费用。</td></tr><tr><td><code>11208</code></td><td><code>VIDEO_PREMIUM_ONLY</code></td><td>视频需要 YouTube Premium 订阅。</td></tr><tr><td><code>11209</code></td><td><code>VIDEO_LIVE_OR_TOO_LONG</code></td><td>视频要么正在直播，要么过长而无法下载。</td></tr><tr><td><code>11210</code></td><td><code>VIDEO_TOO_LONG</code></td><td>视频过长，无法下载。</td></tr><tr><td><code>11211</code></td><td><code>VIDEO_SIGN_IN_REQUIRED</code></td><td>需要登录。</td></tr><tr><td><code>11301</code></td><td><code>MEDIA_UNAVAILABLE</code></td><td>视频已删除或不再存在</td></tr><tr><td><code>11302</code></td><td><code>MEDIA_PRIVATE</code></td><td>视频或账户为私密</td></tr><tr><td><code>11303</code></td><td><code>MEDIA_GEO_RESTRICTED</code></td><td>视频在该任务所在地区不可用</td></tr><tr><td><code>11304</code></td><td><code>MEDIA_UNSUPPORTED</code></td><td>不可下载的视频：照片、幻灯片、直播，或没有视频格式的帖子，或者视频过长或过大而无法下载</td></tr></tbody></table>


---

# 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/api-reference/cn/cuo-wu-yu-zhuang-tai-ma.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.