> ## Documentation Index
> Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reliability

> Processing, monitoring, retries and safe integration patterns.

HueChat's public API is a synchronous REST API implemented by the HueChat Go
service. The HTTP status and body are the result of that request. Public REST
requests do not appear as queue jobs; background jobs shown elsewhere in the
product are a separate system.

## What HueChat measures

For authenticated developer traffic, HueChat records privacy-minimized hourly
usage by account, API key, HTTP method, route template and status. It measures
request count, errors, `429` responses, response time and response bytes.
Recent failures retain the request ID and error code for diagnosis.

The telemetry does not store your `Authorization` header, plaintext key,
request or response body, query string, or path values such as contact and
appointment IDs. Account administrators can inspect per-key usage in
**Account → Developer API**.

## Design a steady integration

1. Create one scoped key per partner or service and grant only the required
   scopes.
2. Add an IP allowlist when the caller has stable outbound addresses.
3. Set the key RPM to the integration's expected traffic, within the effective
   account limit.
4. Use `external_id` for appointment synchronization and keep the same payload
   when safely replaying a timed-out create.
5. Prefer webhooks over polling, and use bounded list pages for reconciliation.
6. Log HueChat's request ID, HTTP status and documented error `code` on your
   side, but never log the API key.
7. Monitor per-key errors, throttles and latency. Rotate before planned expiry
   and revoke unused keys.

## Retry decisions

| Result                            | What to do                                                                                      |
| --------------------------------- | ----------------------------------------------------------------------------------------------- |
| `400`, `403`, `404`, `409`, `422` | Correct the request, authorization, state or version; do not retry unchanged                    |
| `402 api_not_available_on_plan`   | Ask the account owner to enable API access or change plan                                       |
| `429 rate_limit_exceeded`         | Wait for `Retry-After`, then retry with exponential backoff and jitter                          |
| `429 monthly_quota_exceeded`      | Wait until the next UTC month or ask the account owner to review capacity                       |
| `503 api_policy_unavailable`      | Retry a read with backoff; for a write, preserve the idempotency identity and check the outcome |
| Other `5xx` or network timeout    | Back off; check a write's outcome before replaying it                                           |

For appointment writes, read [Appointments and scheduling](/appointments) for
external identity, optimistic `version`, availability and lifecycle rules.

## Capacity is two-level

The account plan or approved account override sets the shared ceiling. Each key
then has its own equal or lower RPM. A noisy integration can therefore be
contained with a lower key rate without reducing other partners, while the
account ceiling protects total platform capacity. See [Rate limits and
quotas](/rate-limits) for all headers and responses.