Skip to main content
Every Puntego worker endpoint speaks the same error language: a predictable JSON envelope plus a standard HTTP status code. Read the status to decide how to react, and read the reason string to know exactly what happened.

The error envelope

A failed request returns a small JSON body with a single error 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
string
A namespaced reason string, <namespace>/<reason>. Branch on the namespace for routing and on the full string for precise handling.
Some responses add a context field next to 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

A 429 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.
The fix for a 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

The requesting origin is not on the workspace allowlist. Add the exact origin in Dashboard → Install → Domains, then reload. See domains.
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.
The visitor JWT is missing, malformed, or past its roughly 15-minute lifetime. Re-run /boot to mint a fresh session and retry. See authentication.
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.
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.
A test-mode session called a route that only production sessions may use (memory, handoff, Verified Actions). Test mode answers and guides; it records nothing live. It clicks or types only on a domain you verified, after the visitor confirms, and keeps those receipts apart from your live data.
A limiter tripped. Read the bucket field to see which one, wait for the Retry-After interval, then retry. See rate limits.
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 error string for precise messaging.
  • Treat 401 on /chat as “refresh the session” — re-boot and retry once.
  • Treat 401 on identity-bound /boot as terminal for that one-time proof. Mint a fresh proof on the authenticated server; never fall back to anonymous boot.
  • Always honor Retry-After on 429; never retry tighter than the header asks.
  • Treat 5xx as transient and retry with backoff; treat 400 and 403 as 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.