Error handling - Chatropic

The chat UI handles runtime errors for you: failed turns show a user-safe message in the conversation, and the widget stays usable. Your job is mostly diagnosis. This page maps the symptoms you might see to their causes.

Symptom to cause

Symptom	Likely cause	Fix
Widget does not load or shows default branding	Mobile app profile not deployed or not Live	Deploy the profile under Deploy > Mobile app
Chat fails immediately on every message	Invalid or revoked publishable key	Copy a fresh key from the Embed tab
Agent replies with a rate-limit message	Guardrail rate limits reached	Review Agent settings > Security; see Topic & rate controls
Agent replies “I can’t help with that” to valid questions	Topic guardrails too strict, or missing knowledge	Check Security settings and Sources
Action returns a sign-in card unexpectedly	Missing or inconsistent `endUserId`	Pass the same `endUserId` on every mount; see Authentication & identity
Navigation card click does nothing	`onNavigate` not wired (mobile) or listener script missing (web)	See Embed navigation

Guardrail rate limits appear as agent text in the conversation, not as an HTTP error, so users always get a polite response rather than a broken widget.

Observing failures

Chat logs and Inbox in the dashboard hold the full transcript of every conversation, so you can see exactly what the user asked and how the turn failed.
Conversation Evals score real conversations against quality criteria and point at which part of the system caused a low score.
The onAgentDone callback fires even for turns that end in an error message, so analytics can count failed turns.

Escalation as a safety net

Configure an Escalate to human action so that when the agent cannot help, users have a path to a person instead of a dead end.

Activity

Transcripts in Chat logs and Inbox.

Guardrails

Safety controls that shape error behavior.