> For the complete documentation index, see [llms.txt](https://docs.stoqapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoqapp.com/rate-limits.md).

# Rate Limits

## 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:**

```json
{
  "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) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stoqapp.com/rate-limits.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.