---
searchable: false
---

import { Callout } from '@theguild/components'

# Rate Limiting

Rate limiting is a technique for reducing server load by limiting the number of requests that can be
made to a subgraph.

You can use rate limiting feature in order to limit the rate of calling queries and mutations.

## Programmatic Configuration

```ts filename="gateway.config.ts"
import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  rateLimiting: {
    rules: [
      {
        type: 'Query',
        field: 'foo',
        max: 5, // requests limit for a time period
        ttl: 5000, // time period
        // You can use any value from the context
        identifier: '{context.headers.authorization}'
      }
    ]
  }
})
```

# Rate Limiting through `@rateLimit` directive

```ts filename="gateway.config.ts"
import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  rateLimiting: true
})
```

This approach follows the pattern of
[`graphql-rate-limit`](https://github.com/teamplanes/graphql-rate-limit/blob/master/README.md#field-config).

To set rate limit hints in your subgraph schema, the `@rateLimit` directive definition should be
included in the subgraph schema:

```graphql
# Import the directive for Federation
extend schema
  @link(url: "https://specs.apollo.dev/link/v1.0")
  @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@composeDirective"])
  @link(url: "https://the-guild.dev/graphql/mesh/spec/v1.0", import: ["@rateLimit"])
  @composeDirective(name: "@rateLimit")

directive @rateLimit(
  max: Int
  window: String
  message: String
  identityArgs: [String]
  arrayLengthField: String
) on FIELD_DEFINITION
```

Then in the subgraph schema, you can use the `@rateLimit` directive to set rate limit hints on
fields:

```graphql
type Query {
  getItems: [Item] @rateLimit(window: "1s", max: 5, message: "You are doing that too often.")
}
```

## Field Configuration

- `window`: Specify a time interval window that the max number of requests can access the field. We
  use Zeit's ms to parse the window arg, docs here.

- `max`: Define the max number of calls to the given field per window.

- `identityArgs`: If you wanted to limit the requests to a field per id, per user, use identityArgs
  to define how the request should be identified. For example you'd provide just ["id"] if you
  wanted to rate limit the access to a field by id. We use Lodash's get to access nested identity
  args, docs here.

- `message`: A custom message per field. Note you can also use formatError to customise the default
  error message if you don't want to define a single message per rate limited field.

- `arrayLengthField`: Limit calls to the field, using the length of the array as the number of calls
  to the field.
