Missing retry header

owasp:api4:2019-rate-limit-retry-after

Rule Severity:

High

Ensure that APIs returning 429 responses contain a Retry-After header.
This rule applies at the API Specification level (OAS/Swagger).
Endpoints should use proper rate limiting to ensure service availability to all users. The Retry-After header indicates how long a user of an API will need to wait before making a new request.
When an API returns a 429 Too Many Requests response, it typically indicates that the client has sent too many requests in a given amount of time. This is often seen with rate-limited APIs. Adding the Retry-After header to a 429 response provides additional information about when the client can safely make a new request without getting throttled. This helps in clearly communicating to the client how long they should wait before making another request. Without it, clients might continue to hit the endpoint, exacerbating the rate-limiting issue. Clients can programmatically detect the Retry-After header and adjust their request intervals accordingly. This leads to fewer errors and more efficient interactions with the API.

Example Attack Scenario

Distributed Denial of Service (DDoS )Amplification Attacks: Hackers can exploit the absence of a Retry header to amplify (DDoS) attacks through amplification techniques. In the absence of guidance on retry timing, malicious actors can repeatedly bombard vulnerable servers with requests, depleting resources and potentially leading to service degradation or downtime.

1. How to Identify with Example Scenario

responses:  
 '429':    
  description: 
   Rate limit exceeded    # Missing Retry-After header

1. How to Resolve with Example Scenario

responses:
 '429':
  description: 
   Rate limit exceeded
  headers:      
   Retry-After:        
    description: 
     Indicates how long the client should wait before making a follow-up request.        
    schema:          
     type: string 
     # example: 'Mon, 7 Aug 2023 07:28:00 GMT'
     # optionally add examples for both date and delay-seconds        
     examples:          
      http-date:            
       value: 'Mon, 7 Aug 2023 07:28:00 GMT'          
       delay-seconds:            
        value: '120'

2. How to Identify with Example Scenario

Find the text in bold to identify issues such as these in API specifications

2. How to Resolve with Example Scenario

Modify the text in bold to resolve issues such as these in API specifications
References:

More findings

All Findings