Why complexity-based rate limiting?
Traditional REST APIs use request-based rate limiting where every request consumes the same credits, whether you fetch one field or hundreds, and whether you read or modify data—despite the significant difference in server load.
GraphQL's query complexity-based approach solves this by calculating costs based on the actual data requested and operations performed. This gives you more flexibility to request what you need while providing predictable server load.
Rate limit
Zonos uses a point-based system where each query deducts points based on its complexity. You have a pool of available points that:
- Refills at 3,000 points per second (30,000 points per 10 seconds)
- Has a maximum capacity of 300,000 points
This allows you to make occasional bursts of complex queries while maintaining a sustainable request pace.
How query cost is calculated
Every GraphQL request has a cost calculated before execution:
Base costs
- Query: 5 points
- Mutation: 10 points
- Object: 1 point per object returned
- Scalar fields: 0 points (free)
Scalar fields like strings, integers, IDs, and booleans don't add to the cost. You only pay for the base operation and the objects returned.
Example: Simple query
query { landedCost(id: "123") { id createdBy shipToCountry }}Cost breakdown: 5 (base query) + 1 (landed cost object) = 6 points
The scalar fields (id, name, currency) are free.
Example: Query with multiple objects
{ orders(first: 10, filter: { status: COMPLETED }) { edges { cursor node { id } } }}Cost breakdown: 5 (base query) + 10 (10 orders × 1 point each) = 15 points
Example: Mutation
mutation { landedCostCalculate(input: { ... }) { id }}Cost breakdown: 10 (base mutation) + approximately 50 (objects returned) = 60 points
A typical landed cost calculation costs around 60 points in complexity.
Viewing query complexity
Every API response includes a zonos-query-complexity header showing your query's cost:
zonos-query-complexity: 58This header tells you exactly how many points the query consumed. Use it to monitor your API usage and optimize expensive queries.
Handling rate limits
If you exceed your rate limit, you'll receive an error message. To handle rate limits effectively:
Monitor your complexity
Check the zonos-query-complexity header in responses to understand your query costs and identify expensive patterns.
Implement retry logic
If you hit rate limits, implement exponential backoff and retry logic. Since the bucket refills at 3,000 points per second, calculate appropriate wait times based on your query complexity.
Batch efficiently
GraphQL allows you to request multiple queries in a single request:
{ landedCost(id: "landed_cost_123") { id createdAt } order(orderId: "order_123") { id status createdAt }}Best practices
Request only what you need
Query complexity is proportional to the data you request. Structure your queries to fetch only the fields and objects you'll actually use.
query { order(orderId: "order_123") { id status createdAt updatedAt items { id name quantity amount } shipments { id } }}Paginate large datasets
When requesting multiple objects, use reasonable page sizes:
{ orders(first: 100, filter: { status: COMPLETED }) { edges { cursor node { id } } }}Request 10-50 items at a time and paginate through results as needed, rather than requesting hundreds of objects in a single query.
Avoid unnecessary nesting
Each nested object adds to your complexity. Only request nested data when you actually need it.
GraphQL API rate limiting
Learn how Zonos calculates query costs based on complexity.
Zonos rate limits GraphQL API requests based on query complexity rather than request count. This ensures fair usage while allowing you to request exactly the data you need.