Rate limits

The Cooledge API limits how fast you can call it so one integration cannot starve the others. The limits are generous for normal use. A well-behaved integration that paces itself and backs off when asked rarely meets them.

There are two layers, and they exist for different reasons.

The two layers

• A perimeter at the edge. A Web Application Firewall sits in front of the API and watches traffic by IP and path. It is the intended outer defence against floods and abuse, the line that stays up even when everything behind it is having a bad day. Treat it as a backstop you should never reach, not a budget you get to spend.
• A per-key limiter in the application. Behind the perimeter, each API key has its own request budget. This is the limit you design your integration around. It is a sliding window backed by a Redis store, so the budget is measured continuously over the last 60 seconds rather than resetting on a clock boundary.

The per-key limiter is the one you will see day to day, so the rest of this guide is about that.

The default limit

By default each key is allowed 120 requests per minute. Because the window slides, that is roughly two requests per second measured over any 60-second span, not a quota that refills all at once at the top of each minute. The headroom is comfortable for early-access integrations that read and write at a steady pace.

The limit is counted per key, not per business. If you run several keys, each one carries its own 120-per-minute budget.

Getting a higher limit

A heavy integration can be granted more. The limit is an explicit per-key value, so we raise it on the individual key rather than moving you onto a fixed paid tier. There is no hardcoded paid number to reach for. A key is either on the 120-per-minute default or on a higher figure we set for it.

If 120 requests per minute is not enough for what you are building, email Cooledge support, tell us the key prefix and the rate you need and we will set an override on that key.

When you hit the limit

A request that exceeds the per-key budget is rejected with HTTP 429 Too many requests. The response includes a Retry-After header giving the number of seconds to wait before the budget frees up again:

HTTP/1.1 429 Too Many Requests
Retry-After: 7
Content-Type: application/problem+json
x-cooledge-request-id: 3b1c0e2a-7d44-4e91-9a2c-1f0b8e6d5a23

The body is a standard problem-details object, the same RFC 7807 shape every error uses, described in Pagination and errors:

{
  "type": "urn:cooledge:error:rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Retry after 7s",
  "request_id": "3b1c0e2a-7d44-4e91-9a2c-1f0b8e6d5a23"
}

Handle a 429 like this:

• Honour Retry-After. Wait at least the number of seconds it gives you before retrying the request. Do not retry immediately and do not retry in a tight loop.
• Back off exponentially with jitter on repeats. If you keep getting 429s, lengthen the wait between attempts each time (for example one second, then two, then four) and add a small random jitter to each wait. The jitter spreads out a fleet of clients so they do not all retry on the same beat and collide again.
• Slow your steady rate, not just your retries. A persistent stream of 429s means your normal request rate is above the budget. Add a small pause between calls or batch your work so you stay under 120 per minute, rather than relying on retries to absorb the overflow.

Availability over enforcement

The per-key limiter is built to fail open. If its Redis store is briefly unreachable the limiter lets the request through rather than rejecting it, because a limiter outage must never take working traffic down with it. In that window the perimeter is the line that still holds. This is deliberate, but it means you should not treat the absence of a 429 as proof you are under budget. Pace yourself to the 120-per-minute figure rather than probing for where the limit actually bites.

The request id on every response

Every API response carries an x-cooledge-request-id header, a UUID that identifies that single request in our logs. It is present on successful responses and on errors alike, and the same value also appears as request_id in any problem-details error body.

Log this id for every call your integration makes. When something looks wrong, a 429 you did not expect or any other error, quote the request id to Cooledge support. It lets us find the exact request in our logs in seconds instead of guessing from timestamps.

Where to go next

• Pagination and errors covers cursor pagination on list endpoints and the full RFC 7807 error shape, including the other status codes.
• Authentication covers the key format, the scope list and how to read 401 and 403 errors.
• The API reference is the live, endpoint-by-endpoint specification.