Findings
Missing retry header
Updated: June 19, 2025
Description
Ensure that APIs returning 429 responses contain a Retry-After header.
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.
This rule applies at the API Specification level (OAS/Swagger).
Example Attack
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.
Remediation
Ensure the Retry-After header is present in 429 responses. Define proper rate limiting to avoid attackers overloading the API. Part of that involves setting a Retry-After header so well meaning consumers are not polling and potentially exacerbating problems.
Security Frameworks
Satisfying API requests requires resources such as network bandwidth, CPU, memory, and storage. Other resources such as emails/SMS/phone calls or biometrics validation are made available by service providers via API integrations, and paid for per request. Successful attacks can lead to Denial of Service or an increase of operational costs.
Quite often, APIs do not impose any restrictions on the size or number of resources that can be requested by the client/user. Not only can this impact the API server performance, leading to Denial of Service (DoS), but also leaves the door open to authentication flaws such as brute force.
When an actor claims to have a given identity, the product does not prove or insufficiently proves that the claim is correct.