> ## Documentation Index
> Fetch the complete documentation index at: https://developers.qomon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

## How rate limiting works

The API uses a token bucket.

* Bucket capacity: `100` tokens
* Refill rate: `10` tokens per second
* Default request cost: `1` token
* Expensive request cost: `5` tokens

All requests authenticated against the space share the same bucket.

## Expensive endpoints

These synchronous contact write endpoints cost `5` tokens per request:

* `POST /contacts`
* `PATCH /contacts/{id}`

If you want the lower-cost write path, use `POST /contacts/upsert`. It keeps the default request cost of `1` token and is the recommended route for synchronization and mass updates.

## Response headers

Every rate-limited authenticated response includes these headers:

| Header                  | Meaning                                          |
| ----------------------- | ------------------------------------------------ |
| `X-Ratelimit-Limit`     | Bucket shape in the format `burst:100;rate:10.0` |
| `X-Ratelimit-Remaining` | Tokens currently available in your bucket        |
| `X-Ratelimit-Cost`      | Cost of the request that was just evaluated      |
| `X-Ratelimit-Reset`     | Seconds until the bucket is fully refilled       |

When the API rejects a request with `429 Too Many Requests`, the response also includes:

| Header        | Meaning                                                |
| ------------- | ------------------------------------------------------ |
| `Retry-After` | Whole seconds to wait before retrying the same request |

## Example

```http theme={"system"}
X-Ratelimit-Limit: burst:100;rate:10.0
X-Ratelimit-Remaining: 94
X-Ratelimit-Cost: 5
X-Ratelimit-Reset: 0.6
```

<Card title="Best practices" type="tip">
  * Prefer `POST /contacts/upsert` for large imports and recurring syncs.
  * Spread bursts when you send expensive synchronous contact writes.
  * Read `Retry-After` before retrying a `429` response.
</Card>