Rate limits

The limits

Removals are budgeted on their own because nobody sees them happen: an unbudgeted key could remove thousands of customers an hour, each one firing the venue's automations.

Rather than learn these from a 429, ask: GET /key answers the calling key's own limits.

Headers on every answer

RateLimit-Policy: "default";q=300;w=60
RateLimit: "default";r=287;t=42

These describe the key's per-minute allowance. RateLimit-Policy is the allowance: q requests every w seconds. RateLimit is where you are now: r requests left, and t seconds until the window resets.

Over a limit

Whichever limit is reached, the request is refused with a 429 rate_limited and a Retry-After header in seconds. Wait that long, then carry on. detail says which limit it was.

{
  "type": "https://developers.hatcel.com/errors#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Try again in 18 seconds.",
  "request_id": "req_8c1f2e4b6a9d0c3e5f7a1b2c"
}

Unusual activity

Hatcel checks every live key each hour. A key that suddenly reads far more than it usually does - most of a workspace's customers in a day, or several times its normal requests in an hour - is paused, and the people who manage the workspace's API keys are emailed. A new key's first sync is not held against it.

A paused key gets a 403 key_paused on every request until somebody resumes it on the key's page in Settings > Developers. Retrying will not help, so stop and tell a person.

{
  "type": "https://developers.hatcel.com/errors#key_paused",
  "title": "This key is paused",
  "status": 403,
  "code": "key_paused",
  "detail": "This key was paused because of unusual activity. Somebody who manages API keys can resume it in Settings > Developers.",
  "request_id": "req_8c1f2e4b6a9d0c3e5f7a1b2c"
}