跳转到主要内容

​
错误响应格式

所有 API 错误返回 JSON： 
{
  "detail": "Invalid or missing API key"
}

​
HTTP 状态码

StatusDescription
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 错误

ErrorCauseClose code
Invalid API key连接消息中密钥缺失或无法识别1008
Rate limit exceeded并发连接数过多1008
Connect timeout10 秒内未收到 JSON 连接消息1008
Target connection failed代理节点无法连接到目标 WS1011
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 断开。