# operation-rate-limiting-defined

Source: https://apigenie.pl/docs/linter/swagger/rules/operation-rate-limiting-defined

This rule checks whether the responses of Swagger 2.0 operations declare rate
limiting headers.

## Rule Details

When an API limits the rate of requests, declaring the rate limiting headers
lets consumers pace their requests and recover from throttling.

The `operation-rate-limiting-defined` rule checks the responses of every
operation:

- a response whose status code starts with `2` or `4` must declare a
  `RateLimit-Limit`, `X-RateLimit-Limit` or `X-Rate-Limit-Limit` header,
  otherwise the rule reports `Missing rate limiting header`;
- a `429` or `503` response must declare a `Retry-After` header, otherwise the
  rule reports `Missing Retry-After header`.

A `429` response is therefore checked for both headers. Header names are
compared case-sensitively. When a response is a `$ref` to a shared response
under the root `responses`, the headers of the referenced response are used.
The `default` response and other status codes are not checked.

## Configuration

None.

## Examples

**Good**. The success response declares a rate limit header, and the shared
`429` response declares both `Retry-After` and a rate limit header.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
          headers:
            X-RateLimit-Limit:
              description: The number of requests allowed per hour.
              type: integer
        '429':
          $ref: '#/responses/TooManyRequests'
responses:
  TooManyRequests:
    description: Too many requests.
    headers:
      Retry-After:
        description: The number of seconds to wait before retrying.
        type: integer
      RateLimit-Limit:
        description: The number of requests allowed per hour.
        type: integer
```

**Bad**. The `200` response has no rate limit header and the `503` response has
no `Retry-After` header.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
        '503':
          description: The service is unavailable.
```

## When Not to Use It

You may disable this rule if your API does not impose any rate limits.

## Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are
linted by the OpenAPI linter, which has a rule of the same name.