> ## Documentation Index > Fetch the complete documentation index at: https://docs.55-tech.com/llms.txt > Use this file to discover all available pages before exploring further. # Scraping API Error Handling > Scraping API 错误码、封锁检测和重试策略。 ## 错误响应格式 所有 API 错误返回 JSON： ```json theme={null} { "detail": "Invalid or missing API key" } ``` ## HTTP 状态码 | Status | Description | | ------ | -------------------------------------------------------------------- | | `200` | 成功 — 目标响应已代理（检查 `meta.blocked` 以确认是否被封锁） | | `401` | 未授权 — API 密钥缺失 | | `403` | 禁止访问 — API 密钥无效 | | `429` | 速率限制。响应头包含 `Retry-After`、`X-RateLimit-Limit`、`X-RateLimit-Remaining` | | `502` | 网关错误 — 该域名没有可用的健康代理节点 | | `504` | 网关超时 — 目标未在超时时间内响应（默认 30 秒） | ## 封锁检测 每个抓取响应都包含 `meta.blocked` 字段： ```json theme={null} { "meta": { "status": 403, "blocked": true, "agent": { "id": "scraping-de5" } }, "raw": "Access Denied..." } ``` 当 `meta.blocked` 为 `true` 时： * 被封锁的代理节点会自动从该域名中排除 * 您的下一个请求将路由到其他代理节点 * 响应仍然包含完整的目标响应体供您检查 您可以查看某个域名的按代理节点健康状态： ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ https://scraping-api.55-tech.com/network/health/example.com ``` 健康端点返回三种状态：`available`、`limited`（临时排除）和 `unavailable`（较长时间排除）。代理节点会自动恢复。 ## 重试策略 ### 速率限制 (429) 使用指数退避策略：等待 1 秒、2 秒、4 秒，依此类推。通过 `GET /usage` 查看当前速率限制状态。 ### 被封锁 (meta.blocked = true) 无需客户端重试逻辑。API 会自动将您的下一个请求路由到其他健康的代理节点。正常继续发送请求即可。 ### 浏览器验证失败 (502) 如果您在 `/browser` 上使用 `expectSelector` 或 `expectContains`，且渲染页面不匹配，API 会自动在不同节点上重试后再返回错误。第一次失败无需客户端重试。 ### 超时 (504) * 增加 POST 请求体中的 `timeout` 字段值（默认：30 秒） * 对于 `/browser`，浏览器启动需要约 2-5 秒 — 请相应设置 `timeout` * 使用 `X-Geo` 选择地理位置更接近目标的代理节点 * 使用 `GET /debug/pick?url=...` 预览将选择哪个代理节点 ### 无可用代理节点 (502) 该域名的所有代理节点暂时被排除。稍等片刻后重试，或使用 `GET /network/health/{domain}` 检查恢复状态。 ## WebSocket 错误 | Error | Cause | Close code | | ------------------------ | ------------------ | ---------- | | Invalid API key | 连接消息中密钥缺失或无法识别 | `1008` | | Rate limit exceeded | 并发连接数过多 | `1008` | | Connect timeout | 10 秒内未收到 JSON 连接消息 | `1008` | | Target connection failed | 代理节点无法连接到目标 WS | `1011` | | Agent unavailable | 没有可用的代理节点处理该请求 | `1011` | ## AMQP 错误 AMQP 错误以 SSE 事件形式交付： ``` event: error data: {"message": "agent error: connection refused", "code": 1011} ``` 错误事件发送后，SSE 流将关闭。 ## 常见错误 ### 缺少目标 URL ```bash theme={null} # Wrong: no URL specified curl -H "X-API-Key: YOUR_KEY" https://scraping-api.55-tech.com/fetch # Right: URL in header curl -H "X-API-Key: YOUR_KEY" \ -H "X-Target-URL: https://example.com" \ https://scraping-api.55-tech.com/fetch ``` ### 无效的地理代码 ```bash theme={null} # Wrong: full country name -H "X-Geo: Germany" # Right: ISO 2-char code -H "X-Geo: DE" ``` ### WebSocket 连接超时 包含 `apiKey` 和 `url` 的第一条 JSON 消息必须在打开 WebSocket 连接后 **10 秒**内发送，否则连接将以关闭代码 `1008` 断开。