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

# Rate Limits

> Understanding rate limits and usage tracking

# Rate Limits

Truedy API uses configurable **per-minute** rate limits to ensure fair usage and prevent abuse. Limits are applied per organization (per API key).

## Current behavior

* **Per minute**: The API allows a fixed number of requests per minute per organization. The default is **100 requests per minute** and can be configured per deployment (`RATE_LIMIT_PER_MINUTE`). There are no per-hour or per-day tiers in the current implementation.
* **No rate limit headers**: Responses do not currently include `X-RateLimit-*` or `Retry-After` headers. Use the 429 response body to know the limit and when the window resets.
* Rate limiting can be disabled by the deployment (e.g. `RATE_LIMIT_ENABLED=false`). When disabled, no 429s are returned for over-limit requests.

## Rate limit exceeded (429)

When the per-minute limit is exceeded, you receive a **429 Too Many Requests** response with the same envelope as other API errors:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "reset_at": "2026-03-03T12:01:00.000000Z"
    }
  },
  "meta": {
    "request_id": "uuid",
    "ts": "2026-03-03T12:00:00.000000Z"
  }
}
```

* **details.limit**: The per-minute limit that was applied.
* **details.reset\_at**: ISO 8601 timestamp when the current window resets (approximately the start of the next minute).
* **meta.request\_id**: Use when contacting support.
* **meta.ts**: Server time when the response was generated.

Use `reset_at` to wait before retrying. Implement exponential backoff when you receive 429s to avoid tight retry loops.

## Best practices

<CardGroup cols={2}>
  <Card title="Use reset_at" icon="clock">
    Wait until after `error.details.reset_at` before retrying when you get 429
  </Card>

  <Card title="Implement backoff" icon="gauge">
    Use exponential backoff when rate limited
  </Card>

  <Card title="Request higher limits" icon="arrow-up">
    Contact [support@truedy.ai](mailto:support@truedy.ai) for higher limits if needed
  </Card>

  <Card title="Use multiple keys" icon="key">
    Distribute load across multiple API keys (each has its own limit)
  </Card>
</CardGroup>

## Handling rate limits

### Exponential backoff

```python theme={null}
import time
import requests
from datetime import datetime, timezone

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            data = response.json()
            reset_at = data.get("error", {}).get("details", {}).get("reset_at")
            if reset_at:
                # Parse and wait until reset (or at least 60 seconds)
                try:
                    reset_dt = datetime.fromisoformat(reset_at.replace("Z", "+00:00"))
                    wait_secs = max(60, (reset_dt - datetime.now(timezone.utc)).total_seconds())
                except Exception:
                    wait_secs = (2 ** attempt) * 60
            else:
                wait_secs = (2 ** attempt) * 60
            time.sleep(min(wait_secs, 120))
            continue

        return response

    raise Exception("Max retries exceeded")
```

## Usage tracking

API requests are logged and tracked. Usage can be viewed in the dashboard where available. For higher limits or custom needs, contact [support@truedy.ai](mailto:support@truedy.ai).

## Increasing limits

1. **Contact support**: Email [support@truedy.ai](mailto:support@truedy.ai)
2. **Specify requirements**: Provide your use case and expected volume
3. **Upgrade plan**: Higher-tier plans may include higher limits