The error envelope
A failed request returns a small JSON body with a singleerror field. The value is a namespaced string in the form <namespace>/<reason>, where the namespace is usually the endpoint family (boot, chat, consent, voice, and so on).
Error response
A namespaced reason string,
<namespace>/<reason>. Branch on the namespace for routing and on the full string for precise handling.error (for example a human-readable message on plan-limit responses), but error is always present and is the field to switch on.
Rate-limit responses are shaped differently
A429 response carries an extra bucket field that names the limiter that tripped, and the error is always rate_limit/exceeded. Every 429 also includes a Retry-After header in seconds.
Rate-limit response
See rate limits for the buckets, their windows, and how to back off on
Retry-After.Status codes
These are the status codes the worker returns, with representative reason strings for each. Branch on the status first; use the reason for detail.Authentication errors: /boot versus /chat
Boot and chat authenticate at different boundaries, and the distinction is intentional.Ordinary
/boot does not use 401. Without a customer_identity_token, boot mints the visitor session from the app ID and verified origin. Origin, workspace, and visitor-ID problems surface as 403 (for example boot/origin_not_allowed or boot/invalid_visitor_id).Identity-bound /boot can return 401. On a workspace eligible for a full assistant session, an explicitly supplied invalid or replayed customer_identity_token returns boot/invalid_customer_identity; expired proof returns boot/expired_customer_identity. Boot fails closed and never silently creates an anonymous assistant session.Restricted /boot is still 200. A valid app and origin receive a features.privacy_controls_only session when normal assistant traffic is unavailable or the global killswitch is active. It preserves inspect/Forget access, but its JWT cannot authorize chat or normal runtime routes. This restriction is resolved before optional customer identity proof is consumed./chat returns 401 when the Authorization: Bearer <visitor-jwt> header is missing or invalid (chat/unauthorized), and also when the token has expired (jwt_expired). The visitor JWT minted at /boot has roughly a 15-minute lifetime, so a long-lived tab can hit an expired token.401 on /chat is to call /boot again to refresh the visitor session, then retry the chat request with the new token. See authentication for the full token lifecycle.
Common situations
403 boot/origin_not_allowed
403 boot/origin_not_allowed
The requesting origin is not on the workspace allowlist. Add the exact origin in Dashboard → Install → Domains, then reload. See domains.
403 chat/tenant_not_enabled
403 chat/tenant_not_enabled
The visitor session cannot access normal assistant traffic for this workspace. A new boot may return a
200 privacy-controls-only session so inspect/Forget remains available, but that restricted JWT still cannot authorize chat.401 boot/invalid_customer_identity or boot/expired_customer_identity
401 boot/invalid_customer_identity or boot/expired_customer_identity
An explicitly supplied one-time customer identity token is invalid, expired, bound to another app, or already consumed. Mint a new token on your authenticated server and retry the initial boot once. Do not remove the token and retry anonymously; identity-bound boot intentionally fails closed.
429 boot/test_mode_quota, or the chat_test_mode_limit notice
429 boot/test_mode_quota, or the chat_test_mode_limit notice
A test snippet reached one of its limits. Starts per hour, or the number of different sites a
test key may run on in a day, refuse
/boot with 429 boot/test_mode_quota (bucket says
which). Answers per hour, day or month are answered by the worker itself: the widget shows
“Test mode has reached its answer limit for now” (error_code: "chat_test_mode_limit"), and
the x-puntego-limit-bucket header names the limit. Wait for the Retry-After interval;
Dashboard → Install shows the answers left. If a test key was copied somewhere it should
not be, choose Replace test key there: the old key stops everywhere and the new one can
start again right away, but answers already used this hour, day or month still count, because
answer limits belong to the workspace, not to the key.429 rate_limit/exceeded
429 rate_limit/exceeded
A limiter tripped. Read the
bucket field to see which one, wait for the Retry-After interval, then retry. See rate limits.200 boot with features.privacy_controls_only
200 boot with features.privacy_controls_only
The app and origin passed validation, but normal assistant traffic is unavailable or the global killswitch is active. The embed exposes privacy controls without a chat composer; inspect/Forget remains available, and all normal runtime routes stay blocked. Full assistant traffic resumes only after the workspace is eligible again.
Handling errors well
- Switch on the HTTP status for control flow, and on the
errorstring for precise messaging. - Treat
401on/chatas “refresh the session” — re-boot and retry once. - Treat
401on identity-bound/bootas terminal for that one-time proof. Mint a fresh proof on the authenticated server; never fall back to anonymous boot. - Always honor
Retry-Afteron429; never retry tighter than the header asks. - Treat
5xxas transient and retry with backoff; treat400and403as terminal until the request or configuration changes.
Authentication
How the visitor JWT is minted at boot and refreshed before it expires.
Rate limits
The buckets, windows, and how to back off cleanly on Retry-After.