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

# Rate limits

> API rate limits per key and how to handle throttling.

Retrac rate limits API requests **per API key** to ensure fair usage.

## Default limit

|                 | Value                           |
| --------------- | ------------------------------- |
| **Window**      | 1 minute (rolling)              |
| **Default cap** | 600 requests per minute per key |

Restricted keys may have a custom limit set at creation time in the dashboard.

## Response headers

| Header                  | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window  |
| `X-RateLimit-Remaining` | Requests remaining in the window                |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets |
| `Retry-After`           | Seconds to wait before retrying after a `429`   |

## When limited

You receive HTTP `429` with error code `rate_limit_exceeded`:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "doc_url": "https://docs.retrac.co/api-reference/errors#rate-limit-exceeded"
  }
}
```

## Best practices

* Cache read responses where appropriate (item lists, location metadata).
* Use exponential backoff when retrying after `429`.
* Respect the `Retry-After` header rather than hammering the API.
* Split high-volume sync jobs across time or use bulk endpoints (`POST /items/bulk` accepts up to 100 items per request).

## Workspace usage limits

Separate from request rate limits, workspaces have **plan limits** on total items, transfers per billing cycle, and locations. Exceeding those returns `403` with code `exceeded_limit`, not `429`.