Rate Limits

The careCycle API limits how many requests each API key can make.

Default limit

Each API key can make 120 requests per minute. Requests are counted per key in fixed one-minute windows, so the count resets when the window ends. Separate keys have separate limits.

careCycle can set a different limit or window length on an individual key. If your integration needs more throughput, contact careCycle support.

Every request counts

Every request made with the key counts toward its limit, including reads and polling. For example, polling a campaign enrollment job for results uses the same budget as the request that started the job. Poll at a modest interval (the enrollment guide suggests every 2-5 seconds) rather than in a tight loop.

When you exceed the limit

Once a key uses its budget for the current window, further requests return 429 Too Many Requests until the window resets:

{
  "message": "API key rate limit exceeded. Please slow down your requests.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 42
}

retryAfter is the number of whole seconds until the current window ends. For the default window, it is between 1 and 60; custom windows can return longer waits. The limit is reported only in the response body: the API does not send Retry-After or RateLimit-* headers.

Repeated requests with an invalid API key are also rate limited and return the same 429 response with RATE_LIMIT_EXCEEDED. Fix the key instead of retrying.

Handling 429 responses

1. Stop sending requests with that key.
2. Wait retryAfter seconds, then retry the request.
3. If you keep hitting the limit, spread requests out: queue work on your side, batch where an endpoint accepts lists, and slow down polling.