Skip to main content

​
Error response format

All API errors return JSON: 
{
  "detail": "Invalid or missing API key"
}

​
HTTP status codes

StatusDescription
200Success — target response proxied (check meta.blocked for block detection)
401Unauthorized — missing API key
403Forbidden — invalid API key
429Rate limited. Headers include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining
502Bad gateway — no healthy agent available for this domain
504Gateway timeout — target did not respond within timeout (default 30s)

​
Block detection

Every fetch response includes a meta.blocked field: 
{
  "meta": {
    "status": 403,
    "blocked": true,
    "agent": { "id": "scraping-de5" }
  },
  "raw": "<html>Access Denied...</html>"
}
When meta.blocked is true:
  • The agent that got blocked is automatically excluded for this domain
  • Your next request will be routed to a different agent
  • The response still contains the full target body for your inspection
You can check per-agent health for a domain: 
curl -H "X-API-Key: YOUR_API_KEY" \
  https://scraping-api.55-tech.com/network/health/example.com
The health endpoint returns three states: available, limited (temporary), and unavailable (longer exclusion). Agents recover automatically.

​
Retry strategies

​
Rate limit (429)

Use exponential backoff: wait 1s, 2s, 4s, etc. Check GET /usage for your current rate limit status.

​
Blocked (meta.blocked = true)

No client-side retry needed. The API automatically routes your next request to a different, healthy agent. Just keep making requests normally.

​
Timeout (504)

  • Increase the timeout field in your POST body (default: 30 seconds)
  • Use X-Geo to pick agents geographically closer to the target
  • Use GET /debug/pick?url=... to preview which agent would be selected

​
No agents available (502)

All agents for this domain are temporarily excluded. Wait a moment and retry, or use GET /network/health/{domain} to check recovery status.

​
WebSocket errors

ErrorCauseClose code
Invalid API keyMissing or unrecognized key in connect message1008
Rate limit exceededToo many concurrent connections1008
Connect timeoutNo JSON connect message within 10 seconds1008
Target connection failedAgent could not connect to target WS1011
Agent unavailableNo agent available for the request1011

​
AMQP errors

AMQP errors are delivered as SSE events: 
event: error
data: {"message": "agent error: connection refused", "code": 1011}
After an error event, the SSE stream closes.

​
Common errors

​
Missing target 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

​
Invalid geo code

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

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

​
WebSocket connect timeout

The first JSON message with apiKey and url must be sent within 10 seconds of opening the WebSocket connection, or it will be closed with code 1008.