Rate Limits

Understand how rate limiting works on the STOQ API and how to handle it in your integration.

Rate Limits

The STOQ API uses a points-based rate limiting system to ensure fair usage and platform stability. Each API request consumes a certain number of points from your allowance, and the limit resets on a rolling window.

How It Works

Every store gets a budget of 360 points per 60-second window. Each API request costs a number of points depending on whether it reads or writes data:

Request Type	Methods	Cost
Read	GET	1 point
Write	POST, PUT, PATCH, DELETE	2 points

Once you've used all 360 points in a window, further requests will be rejected until the window resets.

Example

If your integration only makes GET requests, you can make up to 360 requests per minute. If it only makes write requests (POST, PUT, etc.), you can make up to 180 requests per minute. A mix of both will fall somewhere in between.

Rate Limit Headers

Every API response includes headers to help you track your current usage:

Header	Description	Example
X-RateLimit-Limit	Your total points budget per window	360
X-RateLimit-Remaining	Points remaining in the current window	284
X-RateLimit-Reset	Unix timestamp (in seconds) when the current window resets	1716300120

Example Response Headers

X-RateLimit-Limit: 360
X-RateLimit-Remaining: 284
X-RateLimit-Reset: 1716300120

You can use these headers to pace your requests and avoid hitting the limit.

When You Exceed the Limit

If you exceed 360 points within a 60-second window, the API returns a 429 Too Many Requests response. The response includes an additional Retry-After header telling you how many seconds to wait before retrying.

429 Response Example

Headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 360
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716300120
Retry-After: 24

Body:

{
  "error": "Rate limit exceeded",
  "retry_after": 24,
  "message": "You have exceeded the rate limit of 360 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 24 second(s)."
}

Best Practices

Monitor the headers

Check X-RateLimit-Remaining after each request. If it's getting low, slow down or pause before making more calls.

Respect Retry-After

When you receive a 429, wait at least the number of seconds specified in the Retry-After header before retrying. Retrying immediately will continue to fail.

Use bulk endpoints where available

Some endpoints support bulk operations (e.g., bulk_notify_intent, bulk_destroy). A single bulk request costs the same as one write request (2 points) but can process multiple records — making it far more efficient than individual calls.

Spread requests over time

Rather than sending a burst of requests all at once, distribute them evenly across the 60-second window to stay within limits.

Implement exponential backoff

If you receive multiple 429 responses in a row, increase the wait time between retries. For example, wait 1 second after the first 429, then 2 seconds, then 4 seconds, and so on.

Quick Reference

Parameter	Value
Points per window	360
Window duration	60 seconds
Read request cost	1 point
Write request cost	2 points
Rate limit exceeded status	429 Too Many Requests
Retry header	Retry-After (seconds)