Add `Retry-After` header and use `429` status code on quota-exceeded responses
Author: atkradCreated May 8, 2026Updated Jul 23, 2026
Labelsenhancementexternal
The problem I'm facing
When a key's quota is exhausted, Tyk returns a 403 Forbidden response with no Retry-After header. I have no way to know when the quota resets and am forced to either poll repeatedly or hard-code a wait time. The 403 Forbidden status code is also semantically incorrect. It means "you are not authorized", whereas the correct code for hitting a rate or quota limit is 429 Too Many Requests.
The solution I'd like
When quota is exceeded, Tyk should:
- Return
429 Too Many Requestsinstead of403 Forbidden. - Include a
Retry-Afterheader indicating how many seconds remain until the quota resets.
Expected response:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Content-Type: application/json
{"error": "Quota exceeded"}This behavior is defined in RFC 9110 §10.2.4 and explicitly referenced in RFC 9429 as the standard mechanism to signal when a client should retry after hitting a limit.
Alternatives I've considered
- Implementing exponential backoff on the client side without a
Retry-Afterhint, but this leads to unnecessary load on the gateway. - Reading the quota reset timestamp from
X-RateLimit-Reseton successful responses, but this header is absent on the quota-exceeded error response itself, making it useless at the exact point it is most needed.
Additional context
- RFC 9110 §10.2.4 - Retry-After
- RFC 9429 - RateLimit Header Fields for HTTP
- This affects both per-key quota and org-level quota enforcement.
Source: TykTechnologies/tyk