429 response should be defined

Issue ID: v3-response-429

Average severity: Medium

Description

One or more operations in your API are missing 429 responses. All operations except HEAD operations should have 429 responses defined.

For more details, see RFC 6585.

Example

The following is an example of how this type of risk could look in your API definition:

{
    "responses": {
        "200": {
            "description": "pet response",
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/Pet"
                    }
                }
            }
        }
    }
}

Possible exploit scenario

Attackers strive to make your APIs behave in an unexpected way to learn more about your system or to cause a data breach. We highly recommend that you minimize any risks and clearly specify the data that your API operations can return for each possible response code.

Remediation

Define 429 responses for all operations except HEAD operations.

{
    "responses": {
        "200": {
            "description": "pet response",
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/Pet"
                    }
                }
            }
        },
        // ...
        "429": {
            "description": "Too many requests",
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/responses/429"
                    }
                }
            }           
        }
    }
}