How can I use OpenAPI overlays to add rate limiting metadata to an API description?

How can I use OpenAPI overlays to add rate limiting metadata to an API description? #

Rate limiting policies are frequently configured in an API gateway (such as Kong, Apigee, or AWS API Gateway) rather than in the OpenAPI document itself, which means developers reading the documentation often have no idea what limits apply until they hit a 429. Since rate limits aren’t part of the core OpenAPI vocabulary, teams typically document them via vendor extensions — and the OpenAPI Overlay Specification is a clean way to attach this metadata without requiring every API author to remember to add it manually.

Defining a Rate Limit Extension Convention #

A simple, consistent shape works well across an entire API:

x-rate-limit:
  requestsPerMinute: 600
  burst: 50
  scope: "per-api-key"

Applying Rate Limit Metadata via Overlay #

overlay: 1.0.0
info:
  title: Rate Limit Metadata Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].get
    update:
      x-rate-limit:
        requestsPerMinute: 600
        burst: 50
        scope: "per-api-key"
  - target: $.paths['/orders'].post
    update:
      x-rate-limit:
        requestsPerMinute: 120
        burst: 10
        scope: "per-api-key"

Documenting the 429 Response Consistently #

Alongside the rate limit metadata, it’s useful to ensure every rate-limited operation documents a consistent 429 response:

  - target: $.paths['/orders'].get.responses
    update:
      "429":
        description: "Too Many Requests — rate limit exceeded. See the Retry-After header."
        headers:
          Retry-After:
            schema:
              type: integer
            description: "Number of seconds to wait before retrying."

Pulling Real Limits From the Gateway Configuration #

Rather than hand-typing limits that can drift from what’s actually enforced, generate the overlay programmatically from your gateway’s configuration export. For example, if using Kong, a script can read the rate-limiting plugin configuration per route and emit matching overlay actions:

for (const route of kongRoutes) {
  actions.push({
    target: `$.paths['${route.path}'].${route.method.toLowerCase()}`,
    update: {
      'x-rate-limit': {
        requestsPerMinute: route.rateLimitingPlugin.minute,
        scope: 'per-api-key'
      }
    }
  });
}

This keeps the documented limits automatically synchronized with the actual enforced configuration, removing an entire class of “the docs are wrong” bug reports.

Rendering the Metadata in Documentation #

Documentation renderers like Redoc support displaying arbitrary x- fields with a bit of custom theming, or you can post-process the metadata into a rendered table using a documentation generator’s templating hooks so that rate limits show up prominently next to each operation.

Applying the Overlay #

redocly join openapi.yaml --overlay rate-limits-overlay.yaml -o dist/openapi.yaml

See What is the OpenAPI Overlay Specification? for the overlay action model, and How can I use OpenAPI overlays to automate changes in a CI/CD pipeline? for how to wire generator scripts like the one above into your build.

Last updated on July 16, 2026.