Rate Limits and Errors

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.

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.
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.