Query Complexity Limits

The API implements query complexity limits to ensure fair resource allocation and protect performance. These limits prevent expensive queries from impacting other users.

What is Query Complexity?

Query complexity is calculated based on the structure and depth of your GraphQL query. Unlike rate limits which count requests, complexity limits analyze what you're requesting within each query.

The API uses a cost calculation similar to GitHub's GraphQL API.

Current Limits

Limit Type	Value	Description
Node Cost	10,000	Maximum cost for a single query
Pagination Maximum	100	Maximum items per page in any connection
Pagination Minimum	1	Minimum items per page

How Complexity is Calculated

Every GraphQL query is assigned a cost based on:

1. Base Field Cost: Each field has a base cost of 1
2. List Multipliers: List fields multiply cost by the number of items requested
3. Nested Fields: Each level of nesting adds to the total cost

Example Calculations

Simple Query (Low Cost)

query {
  product(sku: "123456") {
    name
    priceInCents
  }
}

Cost Breakdown:

• product field: 1
• name field: 1
• priceInCents field: 1
• Total: 3

List Query with Pagination (Medium Cost)

query {
  products(pagination: { first: 25 }) {
    edges {
      node {
        name
        priceInCents
        producerName
      }
    }
  }
}

Cost Breakdown:

• products field: 1
• 25 items × 3 fields each = 75
• Total: 76

Complex Nested Query (High Cost)

query {
  stores(pagination: { first: 50 }) {
    edges {
      node {
        name
        city
        inventories(pagination: { first: 20 }) {
          quantity
          store {
            name
            address
          }
        }
      }
    }
  }
}

Cost Breakdown:

• 50 stores × (2 fields + 20 inventories × 3 fields)
• 50 × (2 + 60) = 50 × 62
• Total: 3,100

Cost in Response

When you execute a query, the API includes the calculated cost in the response extensions:

{
  "data": { ... },
  "extensions": {
    "resourceLimitations": {
      "nodeCostLimit": 10000,
      "nodeCostTotal": 76
    }
  }
}

Use these values to:

• Monitor how close you are to the limit
• Optimize queries to reduce cost
• Debug rejected queries

Handling Complexity Errors

When a query exceeds the complexity limit, you'll receive an error response:

{
  "errors": [
    {
      "message": "Query is too complex. Maximum allowed cost is 10000, but the query has a cost of 15000.",
      "extensions": {
        "code": "COMPLEXITY_LIMIT_EXCEEDED"
      }
    }
  ]
}

Optimization Strategies

1. Request Fewer Fields

Only request the fields you actually need:

Before (Higher Cost):

query {
  products(pagination: { first: 100 }) {
    edges {
      node {
        # All fields requested
        name
        sku
        priceInCents
        producerName
        origin
        countryOfManufacture
        regionName
        shortDescription
        thumbnailUrl
        alcoholPercent
        unitVolumeMl
      }
    }
  }
}

After (Lower Cost):

query {
  products(pagination: { first: 100 }) {
    edges {
      node {
        # Only needed fields
        name
        sku
        priceInCents
      }
    }
  }
}

2. Reduce Pagination Size

Request smaller pages and fetch more pages if needed:

Before:

products(pagination: { first: 100 }) { ... }

After:

products(pagination: { first: 25 }) { ... }

3. Use Pagination Cursors

Fetch data in smaller chunks using cursor-based pagination:

query FirstPage {
  products(pagination: { first: 25 }) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node { name }
    }
  }
}

query NextPage {
  products(pagination: { first: 25, after: "cursor_from_previous_page" }) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node { name }
    }
  }
}

4. Use Filters to Reduce Results

Apply filters to get only the data you need:

query {
  products(
    filters: { 
      minPrice: 2000
      isBuyable: true
    }
    pagination: { first: 25 }
  ) {
    edges {
      node {
        name
        priceInCents
      }
    }
  }
}

Next Steps

• Review Rate Limits for request-based limits
• Explore Quick Start for optimized patterns
• Check the GraphQL API Reference for all available fields