Retries & idempotency.

01Two layers

Failed fetches can be retried inside Hypedata (we rotate proxy, fingerprint, or rendering settings and try again) or outside by your client. They compose: a single API call may translate to several internal retries, and a 429 response from us can be retried by your client.

Internal retries that succeed are reported as a single charged request — you don't pay for the attempts that failed inside our infrastructure. Internal retries that all fail are refunded.

02Server-side retries

Pass a retry object to opt-in to internal retries:

{
  "url": "https://hard-target.example.com/",
  "render": true,
  "retry": {
    "on": ["5xx", "block", "captcha"],
    "max": 2,
    "escalate": true      // upgrade to residential / mobile on retry
  }
}

Internal retries are free up to max=2. Higher values are billable at the per-retry tier cost. Escalation is what lets a cheap default succeed against tough targets without you having to hardcode residential.

03Client-side retries

Retry on:

• 429 with Retry-After — wait the specified duration, then retry.
• 500, 502, 503, 504 — transient platform issues. Exponential backoff.
• Network errors (ECONNRESET, ETIMEDOUT…) — same as 5xx.

Do not retry on:

• 4xx other than 429 — they're permanent without code changes.
• 402 — workspace is out of credits. Retrying won't help.
• 451 — AUP violation. Retrying won't help.

The retryable field in the error envelope is the authoritative signal. SDKs read it for you.

04Idempotency keys

Pass an Idempotency-Key header on any POST request. If the same key arrives within 24 hours with the same body, you receive the cached response — no charge, no duplicate work. Different bodies under the same key return a 409 idempotency_conflict.

curl https://api.hypedata.io/v1/scrape \
  -H "Authorization: Bearer $HYPEDATA_API_KEY" \
  -H "Idempotency-Key: catalog-2026-05-12-42" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","render":true}'

Keys must be unique strings up to 256 chars. UUIDs are perfect. The pattern shines for at-least-once delivery from job queues — even if your worker retries the same task, Hypedata only charges once.

05Backoff algorithm

Hypedata's SDKs use full-jitter exponential backoff. The formula:

delay_ms = random_between(0, min(cap, base * 2**attempt))

With base = 200ms and cap = 30,000ms. If the server response carries retry_after_s, we use max(retry_after_s * 1000, jittered_delay) — never sleep less than the server told us to.

06SDK defaults

Set maxRetries: 0 to disable client retries entirely — useful when your own queue is doing the retrying.