A rate-limited response should distinguish temporary request pressure from invalid input or denied access. Give clients the documented retry guidance they need instead of encouraging repeated immediate calls.
Implementation steps
- Describe limits in the API documentation without exposing private operational details.
- Use a consistent error shape for rejected requests.
- Honor documented Retry-After guidance when it is present.
- Keep retries bounded and preserve the original request context.
A client receiving a temporary limit should not turn one task into a burst of new requests. For a queued operation, polling an existing job may be more appropriate than submitting the same work again.
A check you can run
In a controlled test, reach the documented limit and inspect the error and retry guidance. Verify that the client waits appropriately and stops after its allowed retry budget.
Download preview image