Errors
Partner-facing statuses from mint and related endpoints. Log the body on your server; show users a calm retry / refresh message — never dump stack traces in the widget.
| HTTP | Typical cause | Partner action |
|---|---|---|
400 | Malformed envelope, invalid payload, exp missing / too far | Fix payload schema; keep exp within ~10 minutes |
401 | Unknown / revoked widget token; replayed jti | Rotate or copy token from ChatAdmin; always mint with a fresh jti |
403 | systemName not owned by this tenant | Align BOT_SYSTEM_NAME with ChatAdmin |
429 | Rate limit (IP or tenant) | Back off; mint once per page load, not on every keystroke |
503 | Redis unavailable; tenant inactive; service degraded | Check GET /api/health; wait / alert ops — do not fall back to a hardcoded token |
Widget UX
- If mint fails before init, skip rendering the bubble or show “chat temporarily unavailable”.
- If the session expires mid-chat, prompt refresh rather than inventing a guest user.
Ops checklist: Go-live.