Rate limits and quotas

HueChat applies one effective public API policy to the account and a second cap to each credential. Account enforcement is shared across application hosts and all of the account’s keys, so creating extra keys does not multiply capacity.

How your effective limit is chosen

Layer	Meaning
Account plan	Baseline API availability, requests per minute, 10-second burst, monthly quota and maximum active keys
Account override	A support-approved limit that temporarily or permanently replaces selected plan values
API key	Its `rate_limit_rpm` can be lower than the account RPM, never higher
Personal access token	Its own credential bucket under the same account policy

The effective request rate is the lower of the account RPM and credential RPM. The burst is enforced over 10 seconds. A monthly limit of 0 means unlimited; otherwise the counter resets at the start of each UTC calendar month. Requests rejected before admission do not consume monthly quota. Once admitted, a request consumes one unit even when the endpoint later returns a validation or other application error. Signed-in dashboard traffic is not developer API usage. Some expensive AI endpoints also keep their documented route-specific limit. Both the account/key policy and that narrower limit must allow the request.

Response headers

Authenticated admitted and throttled responses include:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1789167600
X-RateLimit-Burst: 167
X-RateLimit-Monthly-Limit: 100000
X-RateLimit-Monthly-Remaining: 87642

X-RateLimit-Limit is the effective credential RPM. X-RateLimit-Remaining is the lower remaining allowance across the current account and credential minute windows. X-RateLimit-Reset is a Unix timestamp. X-RateLimit-Burst is the effective 10-second burst. For an unlimited monthly policy, monthly limit is 0 and monthly remaining is unlimited.

Minute or burst limit

HTTP/1.1 429 Too Many Requests
Retry-After: 4
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "limit": 1000,
  "retry_after": 4
}

Wait at least Retry-After seconds. Add exponential backoff with jitter if a retry is limited again. Do not run a tight retry loop.

Monthly quota

HTTP/1.1 429 Too Many Requests
Retry-After: 1296000
Content-Type: application/json

{
  "error": "Monthly API request quota exceeded",
  "code": "monthly_quota_exceeded",
  "limit": 100000,
  "retry_after": 1296000
}

Retry-After points to the next UTC month. Ask the HueChat account owner to review the account’s plan when the integration needs sustained additional capacity.

API unavailable on the plan

An account with public API access disabled receives 402 and api_not_available_on_plan. This is a policy response, not a transient server failure; automatic retries will not help.

Use bounded list calls and signed event delivery configured inside HueChat instead of polling each record. Inspect per-key request, error, throttle and latency usage before raising a key rate.

Get started

Working with the API

Integrate

Rate limits and quotas

How your effective limit is chosen

Response headers

Minute or burst limit

Monthly quota

API unavailable on the plan

​How your effective limit is chosen

​Response headers

​Minute or burst limit

​Monthly quota

​API unavailable on the plan

How your effective limit is chosen

Response headers

Minute or burst limit

Monthly quota

API unavailable on the plan