#8191·tyk

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:

  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