Rate Limits

To ensure fair use and platform stability, the GraphQL Storefront API enforces multiple layers of rate limiting. These limits are designed to prevent abuse while supporting normal application and storefront operations.

Finqu aims to keep rate limits as high as possible to support legitimate usage. The limits are primarily in place to prevent abuse or malicious activity, not to restrict typical operations.

How Rate Limiting Works

The API uses several rate limiting mechanisms:

Request Rate Limits

• Requests per minute: The API limits the number of requests you can make per minute. This prevents excessive request volumes.
• Rate limits are enforced using a rolling time window, so bursts may be temporarily allowed as long as the average stays within limits.

Query Complexity Limits

• Each query is evaluated for its complexity score based on the type and amount of data requested.
• More complex or data-intensive queries consume more of your complexity budget.
• The default complexity limit is 1000 per client within a short time window.
• Complex queries (those approaching the complexity limit) have additional per-minute restrictions.

Query Structure Limits

• Query depth: Queries are limited to a maximum depth to prevent deeply nested queries that could impact performance.
• Payload size: Request payloads are limited in size to prevent excessively large queries.

Additional Protections

• Introspection queries: Special rate limits apply to GraphQL introspection queries to prevent schema discovery abuse.
• Failed queries: Repeated failed queries may trigger additional rate limiting to prevent error-based attacks.

Rate Limit Exceeded

If any rate limit is exceeded, the API responds with a 429 (Too Many Requests) status code. When this happens:

• You must wait before making additional requests
• The blocking period varies based on the type of limit exceeded
• No rate limit headers are returned in the response. You will only be notified if you exceed the limit.

Example error response:

{
  "errors": [
    {
      "message": "Rate limit exceeded. Please try again later.",
      "locations": [],
      "path": [],
      "extensions": {
        // Additional error details may be provided here
      }
    }
  ],
  "_httpStatusCode": 429
}

Best Practices

To avoid hitting rate limits:

• Optimize your queries: Request only the data you need and avoid over-fetching
• Control request frequency: Avoid making unnecessary or repetitive requests
• Monitor query complexity: Keep queries simple and focused. Break complex operations into multiple simpler queries if needed
• Handle errors gracefully: Implement retry logic with exponential backoff when receiving 429 responses
• Cache responses: Cache frequently accessed data to reduce API calls
• Batch operations: When possible, combine multiple operations into single requests

If you encounter rate limit errors, reduce your request frequency or query complexity. If you believe your application has legitimate needs that require higher limits, please contact support to discuss your use case.