Rate Limits

Scavio does not throttle by requests per minute. The limit that applies to your key is concurrency — how many requests may be in flight at the same time. Exceed it and the API returns 429 immediately; wait for an in-flight request to finish and retry.

Per-Plan Limits

The official SDKs ship a client-side limiter set to 1 by default. Raise it to your plan's concurrency before running batches.

Tracking your balance

Scavio does not send X-RateLimit-* headers. Credit accounting is returned in the response body instead — every successful data response carries credits_used and credits_remaining alongside data and response_time. For a standalone balance check, call GET /api/v1/usage, which costs nothing.

Handling 429 Errors

A 429 means too many of your requests were in flight at once. It is not a cooldown — as soon as one finishes, the next is accepted. The body tells you your plan, your limit, and how many are currently running.

1. Wait for an in-flight request to complete, then retry
2. Cap your worker pool at your plan's concurrency
3. Implement exponential backoff for repeated 429s
4. Upgrade if you consistently need more parallelism

{
  "error": "Concurrency limit exceeded. Wait for in-flight requests to complete.",
  "plan": "free",
  "concurrency": 1,
  "in_flight": 1
}

Running out of credits

Exhausting your credits is a separate condition and returns 402 Payment Required, not 429.

{
  "error": "Insufficient credits",
  "credit_balance": 0,
  "message": "Your credit balance is too low for this request. Top up credits or upgrade your plan at https://dashboard.scavio.dev/billing",
  "billing_url": "https://dashboard.scavio.dev/billing"
}

Tips

• Cache results where possible to reduce API calls
• Batch related queries rather than making many small requests
• Monitor your usage in the dashboard to anticipate limit needs