define-429-response

Requires every path operation to define an explicit 429 response with a schema.

Attribute	Value
Category	Operations
Maturity	Platinum
OpenAPI	Swagger 2.0; OpenAPI 3.0, 3.1, 3.2
Starter	Off
Lenient–Strict	Warning
Complete	Error

Intent

Rate limiting is a predictable API failure mode. Documenting its payload lets clients implement controlled backoff and error handling.

Flags

Each path operation that omits the exact 429 response, or defines 429 without a schema. A schema may be declared directly on the response or under any response content type; referenced responses are resolved.

Does not flag

Non-path operations or an explicit 429 response containing at least one schema. A default or 4XX response does not replace the exact status for this rule.

See it fail

responses:
  '200':
    description: OK

Diagnostic: Operations should define `429` response.

Fix it

responses:
  '429':
    description: Too many requests
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'

Configure

profiles:
  default:
    rules:
      extends: [recommended]
      override:
        define-429-response: error

Nearby: retry-after-for-429, rate-limit-headers.