Rate-Limit Errors Developers Can Retry on Purpose

Developers can respect a limit they can see. Return 429, a stable code, which bucket they hit, and Retry-After in seconds. A body that says 'slow down' without a number produces a retry loop with a random sleep, which is how you get a second spike.

Distinguish account limits, route limits, and burst limits. The fix for each is different. Creating a new API key is not the fix for a per-IP burst, and you should say so.

Evaluators trip limits that production tenants never see, because the sample retries aggressively or because ten people in one office share an address. If the first hour shares a production budget, your best prospects look like abuse.

Give sample apps and CLI login a separate, documented budget. When they exceed it, the error should point at the sample's retry, not at 'contact sales.'

Honor Retry-After once or twice inside the SDK, then throw the rate-limit error with the code intact. Infinite retries inside the SDK hide the limit from the developer and from your probe.

Capture the probe when you give up: code, route template, and how long you waited. Do not capture the request body.

If new identities hit the same route in the first ten minutes, the quickstart is looping. Fix the sample before you raise the global limit. The drafts will say 'I was running the example' over and over. Believe them.