# Rate Limits and Errors

> Rate limits, other limits and the status codes the API returns.

Source: https://docs.capaone.com/capaone/mcp-and-api/rate-limits-and-errors/  
Product: CapaOne — a separate CapaSystems product; do not apply this page to any other.

Limits that keep the API fast for every organization, and the status codes you can get back.

## Rate limits

- **About 60 requests per minute per organization**, shared by all of the organization's keys and
  MCP tool calls. The budget refills continuously, so a client that stays at one request per second
  is never limited.
- **Short bursts per key** are also capped at the edge, so spread requests out instead of sending
  them all at once.

Successful responses carry `X-RateLimit-Remaining`, the requests left in the current budget. A
limited request gets `429 Too Many Requests`, usually with a `Retry-After` header giving the seconds
to wait.

When `Retry-After` is missing, back off exponentially: wait 1, 2, 4, 8 seconds between retries.

```sh title="Retrying in a shell script"
for attempt in 1 2 3 4 5; do
  status=$(curl -s -o devices.json -D headers.txt -w '%{http_code}' -H "X-Api-Key: $CAPAONE_API_KEY" "$URL")
  [ "$status" != "429" ] && break
  wait=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
  sleep "${wait:-$((2 ** attempt))}"
done
```

## Other limits

- Only `GET` and `HEAD` requests are accepted. Anything else returns `405`.
- A page of the device list holds 25 devices by default and at most 200. A larger `pageSize`
  returns `400`.
- `device/group-by` and the `group_devices` tool return 25 groups per page by default and at most
  100, with `totalGroups` saying how many there are.
- A page of devices with `projection` that would exceed 16 MB returns `400`: narrow the filter,
  ask for fewer fields or use a smaller `pageSize`.
- The MCP tools keep answers small enough for an agent. `get_device` returns at most 200 entries
  per section, 50 by default. Free-text searches take at most 200 characters.
- `get_device`'s patch sections leave out the CapaPacks not installed on the device, and say how
  many they left out. `get_patch_compliance` lists at most 100 applications, 25 by default.
- Event summaries cover at most 92 days per call.
- Admin On Demand data covers at most 92 days per call, the last 30 by default. `get_elevations`
  returns at most 200 entries per page of a device's log, 50 by default, and at most 100 users or
  processes, 20 by default.
- `get_vulnerabilities` returns at most 200 CVEs, 20 by default, with descriptions cut to 400
  characters, and at most 30 scans of history, 8 by default.
- `get_events` covers at most 92 days per call. Its `events` view returns at most 100 events per
  page, 25 by default, with descriptions cut to 500 characters; `devices` at most 100 devices, 20 by
  default; and `values` at most 200 values.

## Status codes

| Status | Meaning | What to do |
|---|---|---|
| `200` | Success. | |
| `400` | The filter or a query parameter is invalid. The body says which field, operator or value. | Fix the request. |
| `401` | The API key is missing, unknown, expired or revoked. | Check the `X-Api-Key` header, or get a new key. |
| `403` | The organization ID in the path is not the key's organization, or the organization has no active contract. | Use the organization ID the key was issued for. |
| `404` | The path is not part of the API. | Check the path against the [API Reference](https://mcp.capaone.com/docs/api/). |
| `405` | The method is not `GET` or `HEAD`. | Use `GET`. |
| `429` | Rate limited. | Wait for `Retry-After`, then retry. |
| `5xx` | A problem on our side. | Retry with backoff. Contact CapaOne support if it persists. |