Skip to content

Return standard 429 Retry-After headers for polite backoff

Give SDKs, webhook workers, and mobile apps exact Retry-After seconds and structured quota errors when limits engage.

Copy the prompt and paste it into the AI assistant you already use.

Configuring polite HTTP 429 rate-limit responses

  1. 01

    Set accurate Retry-After seconds

    Compute exact seconds until window capacity reopens rather than returning static guesswork.

  2. 02

    Distinguish quota vs burst limits

    Return distinct error codes for temporary RPM bursts versus exhausted monthly plan quotas.

  3. 03

    Include reset epoch timestamps

    Expose X-RateLimit-Reset alongside remaining quota headers for frontend progress bars.

  4. 04

    Verify retry helper integration

    Test client retry libraries against throttled sandbox keys to confirm clean exponential pause.

Common questions

Why return Retry-After instead of a generic 500 or bare 429?

Standard Retry-After headers let worker queues and SDKs pause the exact required duration instead of hammering your endpoint blindly.

Can we customize the 429 JSON body format?

Yes. Define custom error JSON templates including support links, current tier names, and upgrade URLs.

Does a blocked 429 request consume any model tokens?

Zero tokens—rate-limit checks run at the edge gateway before any prompt formatting or model call.