Limits and retries

Each plan sets how many requests may run at the same time and how many may start per second. When you go over, the API answers at once with a 429 and charges nothing.

The two limits

LimitError codeWhat it means
Per secondrate_limitedMore requests started this second than your plan allows. Short bursts of up to twice the rate are let through.
At the same timeconcurrency_limitedAs many of your requests are still running as your plan allows. Wait for one to finish.

Both errors carry retry_after_ms in the error object:

HTTP/2 429

{
  "error": {
    "code": "rate_limited",
    "message": "Your plan allows 1 requests per second.",
    "retry_after_ms": 1000
  },
  "request_id": "req-1a"
}

When the pool is busy

If all modems are in use, your request waits up to 15 seconds for a free one. Higher plans are served first. If none becomes free you get busy (503) with retry_after_ms; nothing is charged.

Timeouts

The target has your plan's timeout (30 to 120 seconds) to answer; timeout_ms can shorten it. Set your own HTTP client's timeout higher than that: add 20 seconds for a possible wait in the queue, and another 30 when you use fresh_ip. With the default settings 150 seconds is safe on every plan.

Sizes

Retrying

You gotDo this
rate_limited, concurrency_limited, busy, maintenance, executor_unavailable, rotation_failedWait retry_after_ms (or a second or two) and send again. Not charged.
timeout, target_unreachable, connection_failed, tls_errorThe target or the path to it failed. One or two retries are reasonable; a different modem may succeed. Not charged.
HTTP 200 from us with a target status of 403, 429 or 5xxThe target answered, so the request is charged. Retry with fresh_ip or a new session if the target is rejecting the IP.
Any other 4xx from usFix the request. Retrying unchanged gives the same answer.

A request is not idempotent just because it failed. If a POST timed out, the target may still have processed it.