Overview

The API enforces three independent rate limits to ensure fair usage and system stability. All must pass for a request to proceed.

Request rate limit

Each API key can make up to 500 requests per minute. This limit applies regardless of query complexity or operation type, every request counts as one.

Response headers

Every response includes request rate limit headers:

Complexity rate limit

In addition to the request limit, each API key has a complexity budget. Every operation has a complexity score based on the fields and nesting depth you request. The more data your operation asks for, the higher its cost.

• Your budget starts at 750 points and refills fully every 15 seconds (50 points per second).
• Each operation consumes points equal to its complexity score, with a minimum cost of one point.
• Mutations are more expensive and they consume 5x the complexity points of an equivalent query. For a typical single-field mutation this means a cost of 5 points instead of 1.
• Operations with a complexity score above 750 are rejected before execution.

How complexity is calculated

Complexity is determined by static analysis of your query before it runs. Deeper nesting and more fields increase the score. The X-Complexity-Cost header on every response tells you what your query cost.

Response headers

Every response includes complexity rate limit headers:

Write rate limit

Mutations have a dedicated rate limit of 60 per minute per API key, in addition to the request rate limit and complexity budget. This limit only applies to mutations, queries are not affected.

Response headers

Mutation responses include write rate limit headers:

Handling rate limits

When you receive a 429 Too Many Requests response, you have exceeded the request limit, the complexity budget, or the write rate limit.

1. Check the Retry-After header to determine when to retry
2. Back off and retry after the indicated time
3. Do not retry immediately, repeated 429s will not reset the window

When throttled by the complexity budget, the response body includes a GraphQL error:

{
  "errors": [
    {
      "message": "Complexity budget exhausted. Try a less complex query or wait for your budget to restore.",
      "extensions": {
        "code": "THROTTLED"
      }
    }
  ]
}

Best practices

• Batch related data into a single query. GraphQL lets you request multiple fields in one request, use this to reduce your request count.
• Request only the fields you need. Smaller queries have lower complexity scores so you can make more of them before exhausting your budget.
• Monitor your headers. Watch X-RateLimit-Remaining, X-Complexity-Remaining, and X-Write-RateLimit-Remaining to slow down before hitting limits rather than reacting to 429s.
• Avoid deeply nested queries. Nesting increases complexity quickly so if you need data from multiple levels consider breaking it into separate queries.

Need help?

If you run into any issues or have questions, please reach out to our Support Engineering team by opening a ticket via the Dashboard: https://dashboard.meter.com/support