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

# Rate Limits

> Understand API request limits and retry headers

Duckie API rate limits use one-minute windows. Every authenticated request is checked against layered limits.

| Bucket                                              | Default limit                       |
| --------------------------------------------------- | ----------------------------------- |
| Missing or invalid key attempts                     | 60 requests/minute/IP               |
| Global key traffic                                  | 5,000 requests/minute/key           |
| Global organization traffic                         | 25,000 requests/minute/organization |
| Runs list                                           | 600 requests/minute/key             |
| Run tool options                                    | 600 requests/minute/key             |
| Run detail                                          | 2,400 requests/minute/key           |
| Tools, agents, guidelines, guardrails, and runbooks | 2,400 requests/minute/key           |

## Rate-Limit Headers

Successful authenticated responses include rate-limit headers for the active limiting bucket.

```http theme={null}
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1780444830
```

| Header                  | Meaning                                  |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Request limit for the active bucket      |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the bucket resets    |

## Rate-Limited Responses

When a request exceeds a limit, Duckie returns `429 rate_limited`.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780444830
```

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "request_id": "req_123",
    "retry_after": 12
  }
}
```

Wait at least the `Retry-After` number of seconds before retrying. If you are exporting a large data set, keep using cursor pagination and back off when `X-RateLimit-Remaining` gets low.