Clavem

Rate limiting

Rate limiting is the practice of capping how many requests a client can send to a service within a fixed time window and rejecting the excess, usually with an HTTP 429 Too Many Requests response.

How it works

The server counts requests per identity in a window of time. The identity might be an IP address, an API key or, for a license service, the license key in the request. When a count passes the limit, the server stops doing the work and answers 429. RFC 6585 defines that status and says the response may include a Retry-After header. RFC 9110 defines the header’s value as either a number of seconds or an HTTP date.

The standard does not say how to identify the client or how to count. Each service chooses, so read its documentation.

Clavem’s limits

Surface Limit Counted per
License API (activate, validate, deactivate) 120 requests per 60 seconds IP address
License API 60 requests per 60 seconds License key
Releases endpoint (update checks) 120 requests per 60 seconds IP address, counted separately from the License API
Management API 300 requests per 60 seconds API key

A License API request has to pass both the per-IP and the per-key limit. Over a limit, Clavem answers 429 with Retry-After: 60:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{"valid": false, "error": "Too many requests. Try again in a minute."}

Worked example: an office behind one address

This uses made-up numbers. An office of 40 people sits behind one public IP address, because of NAT. At 9:00 they all open your app within a minute, and each app validates once. That is 40 requests against a budget of 120, a third of it. If each app also validates again when a window regains focus, it is 80, still under.

Now a 150-person company with the same pattern. The first 120 calls pass and the last 30 get a 429. Each key still has its own budget of 60, so no single user is the problem. The IP is.

A bug makes it worse. An app that retries every second after a failure sends 60 requests a minute for that one key. It reaches the per-key limit within a minute, and the next call gets a 429.

What the app should do

  • Validate once per launch, with a short timeout, not in a loop.
  • On 429, on a 5xx or with no network, verify the stored signed token offline and carry on if it is fresh.
  • Read Retry-After and do not call again before it passes.
  • Keep update checks separate. They have their own budget, so they do not use up validation calls.
async function checkOnLaunch(call, verifyStoredToken) {
  let res;
  try {
    res = await call();
  } catch {
    return verifyStoredToken();            // no network
  }
  if (res.status === 429) {
    const seconds = Number(res.headers.get('retry-after')) || 60;
    scheduleNextCheck(seconds);            // your own timer, not a retry loop
    return verifyStoredToken();
  }
  if (res.status >= 500) return verifyStoredToken();
  return (await res.json()).valid ? 'licensed' : 'invalid';
}

This was run against a mocked 429, a 200 and a network error. In all three cases the customer stayed licensed, with the 429 and the network error falling back to a fresh stored token. The scheduleNextCheck function is yours to write.

Rate limits versus plan limits

A rate limit is about speed. A plan limit is about volume. Clavem’s plan limits count active licenses, and they never stop validation, activation or downloads. Validation calls are not metered, which is on the pricing page. A 429 does not mean the account is over its plan.

How Clavem handles it

The numbers above are the whole policy. The API reference documents the 429 responses, and the management API’s structured error uses the code rate_limited. Treat the limits as protection, plan one validation per launch, and let the signed token carry the app through the gaps.

Questions

What does HTTP 429 mean?

It means the client sent too many requests in a given time. The server may add a Retry-After header saying how long to wait before trying again.

Does a rate limit mean I am being charged for requests?

Not for the Clavem License API. Validation calls are never counted or charged. The limits exist to stop abuse and are not a quota.

Sources

  1. RFC 6585, Additional HTTP Status Codes (429 Too Many Requests)
  2. RFC 9110, HTTP Semantics (Retry-After)