This article helps you stay inside the HueChat API limits and understand the error responses you may see. Full reference is in the Developer Hub at https://developers.huechat.ai.
| Credential or surface | Limit |
|---|---|
| Personal access token | 1,000 requests per minute |
| Scoped API key | The key's own limit, 1 to 100,000 per minute (default 1,000) |
AI routes under /api/v2 |
Burst of 10, then 1 request every 2 seconds |
Limits are per minute and per credential. Short bursts above the per-minute rate are tolerated up to about one sixth of the limit. Requests are also limited per IP address, and request bodies are capped at 20 MB.
Every response tells you where you stand:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1712345738
X-RateLimit-Reset is a Unix timestamp for the start of the next window. Watch X-RateLimit-Remaining and slow down before it reaches zero.
You receive 429 Too Many Requests with a Retry-After header in seconds and a body like { "error": "Rate limit exceeded" }. Wait for Retry-After, then back off exponentially if it happens again. Do not retry in a tight loop; that only extends the block.
To stay under the limit, use one bounded list call instead of polling each record, move event-driven work to webhooks (a subscription costs no requests), and give each integration its own scoped key.
| Status | Meaning | Usually |
|---|---|---|
400 |
Bad request | A malformed body or parameter |
401 |
Unauthorized | Missing or invalid credential, or the Bearer prefix is missing |
403 |
Forbidden | The account in the URL is not yours, the key lacks a scope, the IP is not on the allowlist, or your role is too low |
404 |
Not found | The id does not exist in your account |
422 |
Unprocessable | The body parsed but failed validation |
429 |
Too many requests | See rate limits above |
500 |
Server error | Check the outcome before retrying a write; contact support if it persists |
Most errors return { "error": "..." }. Validation errors can include extra details specific to the endpoint.
Authorization: Bearer <token>. A raw token returns 401.page=1. A 200 proves the credential works.403, confirm the account id belongs to the key, the administrator who created the key still has access, the key has the scope for that route, and your server IP is on the key's allowlist.404 inside your own account means the id is absent there. It never reveals whether the id exists in another business.Email support@huechat.ai with the request path, the status code, the X-HueChat-Delivery or request id if you have one, and the time in UTC. Never send the full key; the hc_ prefix is enough to identify it.