---
title: Graceful HTTP 429 & Retry-After Headers | APIkit
description: Emit RFC-compliant HTTP 429 status codes, Retry-After headers, and actionable JSON errors on rate-limited AI calls.
canonical: "https://apikit.ai/j/return-graceful-429-retry-headers"
modified: 2026-11-14
author: apikit.ai editorial team
source: "https://apikit.ai"
category: Response Caching & Rate Limiting
category_url: "https://apikit.ai/j#group-caching-rate-limiting"
---

# 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.

## Prepared starting prompt

Our background workers need standard Retry-After headers and clean JSON reset timestamps whenever an AI endpoint hits its RPM quota.

### Quick scenarios
- **Standard Retry-After:** Emit exact numeric Retry-After seconds calculated from the active sliding window.
- **Custom JSON error schema:** Customize 429 JSON error codes, limit types, and upgrade URLs to match our API conventions.
- **Friendly SDK compatibility:** Ensure Python, Axios, and Fetch retry helpers back off accurately instead of spinning.

- [Request APIkit early access](https://apikit.ai/#waitlist-f73a0d)

## Configuring polite HTTP 429 rate-limit responses

1. **Set accurate Retry-After seconds** — Compute exact seconds until window capacity reopens rather than returning static guesswork.
2. **Distinguish quota vs burst limits** — Return distinct error codes for temporary RPM bursts versus exhausted monthly plan quotas.
3. **Include reset epoch timestamps** — Expose X-RateLimit-Reset alongside remaining quota headers for frontend progress bars.
4. **Verify retry helper integration** — Test client retry libraries against throttled sandbox keys to confirm clean exponential pause.

## Frequently Asked 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.

## Related tasks in this category

- [Cache identical AI responses at the edge for instant hits](https://apikit.ai/j/cache-identical-ai-api-responses.md)
- [Cut LLM costs with semantic similarity response caching](https://apikit.ai/j/enable-semantic-similarity-caching.md)
- [Protect AI endpoints with sliding-window rate limits](https://apikit.ai/j/apply-sliding-window-rate-limits.md)
- [Throttle AI endpoints automatically by customer plan tier](https://apikit.ai/j/throttle-expensive-endpoints-by-plan.md)
- [Manage cache TTLs and purge stale AI outputs instantly](https://apikit.ai/j/configure-ttl-cache-invalidation.md)
- [Stop infinite client retry loops from draining AI spend](https://apikit.ai/j/prevent-prompt-loop-billing-runaway.md)

---

*Published by **Wondel.ai sp. z o.o.** · [apikit.ai](https://apikit.ai) · [About](https://apikit.ai/about) · [Editorial Guidelines](https://apikit.ai/editorial) · [Contact](https://apikit.ai/contact) · [Wondel.ai Products](https://wondel.ai/products)*