# operation-rate-limiting-defined

Source: https://api-genie.dev/docs/linter/openapi/rules/operation-rate-limiting-defined

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. In the rulesets: Recommended at warning, Strict at warning, All at warning.

This rule checks that the responses of every operation declare the rate-limiting headers:
`RateLimit-Limit`, `X-RateLimit-Limit` or `X-Rate-Limit-Limit` on every 2xx and 4xx response,
and `Retry-After` on the `429` and `503` responses.

## Rule details

A client that knows its quota and when to retry stays below the limit; one that does not learns
about it from errors. Declaring the headers in the document tells client authors what to read
and lets generated clients expose them.

The rule reports `Missing rate limiting header` and `Missing Retry-After header` on the response.
It is a warning in the `recommended`, `strict` and `all` rulesets; turn it off when the API
does not limit its clients.

## Examples

**Good**. The quota on the success response, the delay on the `429` response.

```yaml
paths:
  /users:
    get:
      responses:
        "200":
          description: A page of users.
          headers:
            RateLimit-Limit:
              description: Requests allowed per hour.
              schema:
                type: integer
        "429":
          description: Too many requests.
          headers:
            Retry-After:
              description: Seconds to wait before the next request.
              schema:
                type: integer
```

**Bad**. Nothing tells the client about the limit.

```yaml
paths:
  /users:
    get:
      responses:
        "200":
          description: A page of users.
```
