Add `Retry-After` header and use `429` status code on quota-exceeded responses

[atkrad]

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:

1. Return 429 Too Many Requests instead of 403 Forbidden.
2. Include a Retry-After header 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-After hint, but this leads to unnecessary load on the gateway.
• Reading the quota reset timestamp from X-RateLimit-Reset on 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.

[probelabs]

Hello @atkrad, thank you for this excellent and well-researched feature request.

Your proposal to align Tyk's quota-exceeded responses with modern standards by using a 429 Too Many Requests status code and including a Retry-After header is clear and valuable. This change would significantly improve the experience for API consumers, allowing them to handle rate limits more intelligently and efficiently.

Triage

• Category: Enhancement
• Priority: Medium
• Complexity: Moderate

Analysis

Based on an initial review of the codebase, the logic for handling quota violations appears to be located within the QuotaManager middleware. When a quota is exceeded, the CheckRate function in middleware/quota_manager.go returns an error, which is then handled by setting the response code to http.StatusForbidden (403) and writing an error message.

To implement your suggestion, the following changes would likely be needed:

1. Update Status Code: Modify the error handling logic to use http.StatusTooManyRequests (429) instead of http.StatusForbidden.
2. Add Retry-After Header: Calculate the remaining seconds until the quota resets and add it to the response headers. The X-RateLimit-Reset header already contains the reset timestamp, so this value can be used to compute the Retry-After value.

This seems like a feasible and beneficial enhancement for the gateway. We appreciate you taking the time to file this issue.

References

• middleware/quota_manager.go – Contains the core logic for quota enforcement and error handling.

---

Powered by Visor from Probelabs

💡 TIP: You can chat with Visor using /visor ask <your question>