Drıftstack docs
Docs

Too many requests (429) and Retry-After

You might be here because: “Rate limit exceeded” · “Too Many Requests” · “Too many requests. Wait a moment and try again.” · “Too many requests. Wait a moment, then try again.” · “A usage limit was reached. Wait a moment or review your plan, then try again.” · “429” · “Retry-After” · “retry_after_seconds” · “my script is being throttled” · “how many requests per second can I make” · “can I get a higher limit”

Short answer

A 429 with a Retry-After header means one of your account’s request buckets is empty for the moment; wait the number of seconds given and send again — the SDKs do this for you. These are anti-abuse limits, not billing: you pay for how many sessions run at once, not per call. A 429 about the session limit is a different page (see Related).

Check first

  • Which limit? The detail names the bucket and plan, for example “Rate limit for “global” exceeded for tier …“. A plain “Rate limit exceeded.” with no bucket named is a team owner’s limit.
  • Your own numbers: dashboard → Usage → “Limits for your account” lists each limit’s maximum, its recovery per second, and whether support raised it.
  • The desktop app shows “Too many requests. Wait a moment, then try again.” or “Too many requests. Wait a moment and try again.” (older versions: “A usage limit was reached…”).

Likely causes and fixes

  1. A burst. Each bucket holds a burst and refills at a steady rate; on Starter, for example, general calls allow a burst of 120 and 2 per second sustained, and session starts a burst of 10 at 2 per minute. Fix: honour Retry-After and spread calls out; the SDKs back off automatically, capped at 10 seconds.

  2. Session starts and AI messages have their own, smaller buckets. Starting a session (directly or by launching a profile) is the most expensive call; an AI message costs model tokens. The SDKs never retry a message or a transcript read for you — wait retry_after_seconds and call again; the same idempotency key still works.

  3. A session window open while a script runs. A desktop session window polls page state about every 2 seconds on its own agent_sessions:live limit (240 a minute for each session your plan runs at once), so it does not use up your global bucket. Your own reads of the same session routes (the session, page state, network, cookies, downloads) share that live limit with the window — size it for the total.

  4. Working in a team owner’s workspace. A session request charges your bucket, then the owner’s; if the owner’s is empty you get a generic 429 with Retry-After, and your own token is not refunded.

  5. You need more. Higher limits are granted per account on request: email support@driftstack.io with the shape of your workload and the steady rate you expect. A granted increase shows on Usage as “set by support · ends [date]”. Enterprise buckets are set by contract.

If it still fails

If 429s continue although you wait the full Retry-After each time, press Talk to a person in this chat (or open Help) and include: account email, the bucket named in detail, the time, and roughly how many requests per second you send.