# Rate Limits

Trace One APIs apply rate limits to ensure fair and stable usage of our platform. This guide explains how rate limiting works, how to detect it, and how to handle it gracefully in your applications.

## 🔐 Token-Based Rate Limiting

Rate limits are enforced **per authentication token**. Currently, Trace One APIs support only the **OAuth2 Client Credentials flow**, and all limits are applied based on the client identity associated with the token.

## 🕒 Rate Limit Time Windows

Rate limits may be defined across multiple time windows, such as:

- **15-minute window** – Short bursts of activity
- **1-hour window** – Sustained usage over time
- **24-hour window** – Overall daily API consumption


> ⚠️ **Note:** Specific thresholds and limits are subject to change. Please refer to the latest documentation or your integration agreement for exact values.


## 🔁 What Happens When You Exceed a Limit?

If a client exceeds the allowed rate for any time window, the API will respond with:

- `429 Too Many Requests` status code
- A `Retry-After` header indicating how long to wait before retrying


Example response:


```http
HTTP/1.1 429 Too Many Requests
Retry-After: 120
Content-Type: application/json
```


```json
{
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://tools.ietf.org/html/rfc6585#section-4",
  "detail": "Rate limit exceeded. Please wait before retrying."
}
```

## 🧭 Best Practices for Handling Rate Limits

To stay within rate limits and ensure smooth integration:

- Implement exponential backoff or retry delays based on `Retry-After`
- Avoid unnecessary polling or high-frequency API calls
- Use caching where appropriate to reduce repeated requests
- Monitor your usage and error responses


For any questions about rate limits or to request a higher quota, please contact [devsupport@traceone.com](mailto:devsupport@traceone.com).