Scraping API Error Handling

错误响应格式

所有 API 错误返回 JSON：

{
  "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 字段：

{
  "meta": {
    "status": 403,
    "blocked": true,
    "agent": { "id": "scraping-de5" }
  },
  "raw": "<html>Access Denied...</html>"
}

当 meta.blocked 为 true 时：

被封锁的代理节点会自动从该域名中排除
您的下一个请求将路由到其他代理节点
响应仍然包含完整的目标响应体供您检查

您可以查看某个域名的按代理节点健康状态：

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

# 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

无效的地理代码

# Wrong: full country name
-H "X-Geo: Germany"

# Right: ISO 2-char code
-H "X-Geo: DE"

WebSocket 连接超时

包含 apiKey 和 url 的第一条 JSON 消息必须在打开 WebSocket 连接后 10 秒内发送，否则连接将以关闭代码 1008 断开。

入门

API 参考

Scraping API Error Handling

错误响应格式

HTTP 状态码

封锁检测

重试策略

速率限制 (429)

被封锁 (meta.blocked = true)

浏览器验证失败 (502)

超时 (504)

无可用代理节点 (502)

WebSocket 错误

AMQP 错误

常见错误

缺少目标 URL

无效的地理代码

WebSocket 连接超时

​错误响应格式

​HTTP 状态码

​封锁检测

​重试策略

​速率限制 (429)

​被封锁 (meta.blocked = true)

​浏览器验证失败 (502)

​超时 (504)

​无可用代理节点 (502)

​WebSocket 错误

​AMQP 错误

​常见错误

​缺少目标 URL

​无效的地理代码

​WebSocket 连接超时

错误响应格式

HTTP 状态码

封锁检测

重试策略

速率限制 (429)

被封锁 (meta.blocked = true)

浏览器验证失败 (502)

超时 (504)

无可用代理节点 (502)

WebSocket 错误

AMQP 错误

常见错误

缺少目标 URL

无效的地理代码

WebSocket 连接超时