Errors and resilience

Where failures show up

On the element, runtime events arrive as mindset:runtime-event. On the UI-less client, everything arrives on chat.on(). The events reference has every field.

What to do about each one

Branch on the code or reason, never on the message text. Treat a code you don't recognize as a general failure, because new ones can be added.

Check effects before you retry

A turn can fail after the agent has already done something. run_error.effects lists the tool calls that changed something and finished before the failure. Each has toolName, toolCallId and access, and may have a reference (a receipt the system returned) and output.

If effects has entries, a plain retry may repeat them: a second refund, a second booking. Tell the user what already happened, and let them decide.

This UI-less handler puts the rows above into code:

chat.on((event) => {
  if (event.type !== "run_error") return;

  if (event.aborted) {
    showNotice("Stopped.");
    return;
  }

  const done = event.effects ?? [];
  if (done.length > 0) {
    const list = done.map((e) => e.reference ?? e.toolName).join(", ");
    showNotice(`Something went wrong, but these already happened: ${list}. Check before trying again.`);
    return;
  }

  switch (event.reason) {
    case "tool_schema":
    case "unavailable":
      showNotice("The assistant isn't available right now.");
      break;
    case "model_error":
    case "step_limit":
    case "stale_configuration":
    case "failed":
    default:
      showRetryButton(() => chat.retry().catch(() => {}));
      break;
  }
});

showNotice and showRetryButton stand for your own interface code. retry() runs the last turn again and replaces its reply. Its promise rejects if that turn fails too, and the run_error event reports it, so the empty catch only stops an unhandled rejection.

On the element, listen for mindset:runtime-event and read e.detail the same way:

const agent = document.querySelector("mindset-agent");

agent.addEventListener("mindset:runtime-event", (e) => {
  const event = e.detail;
  if (event.type === "run_error" && !event.aborted && event.effects?.length) {
    console.warn("A turn failed after changing something:", event.effects);
  }
});

agent.addEventListener("mindset:error", (e) => {
  const { code, message } = e.detail;
  if (code === "invalid-auth") console.error("Fix getSession:", message);
  else if (code === "stale-configuration") reconfigure(); // your own function that calls configure() again
  else console.error("Mindset error:", code, message);
});

What the SDK already handles

• Renewal. The SDK renews its access token while the page is open, and calls getSession again when it can't.
• A changed agent version. When the agent's active version changes mid-conversation, the SDK fetches the new configuration and runs the turn again, once, before you see anything. That works while the turn hasn't produced output yet.
• A conversation ID it can't use. It starts a fresh conversation and tells you with conversation_id (mindset:conversation on the element), with replacedBecause: "discarded". Store whatever ID arrived last.
• History that won't load. history_settled still arrives, with an empty list, within 15 seconds. It can't tell you whether the history was empty or failed to load.

Spend limits

Each person using an embedded agent has an hourly spend ceiling on their turns, roughly $25 an hour per person on each Mindset server. Past it, their turns are refused until spend in the window drops, and a refused turn fails like any other. See and control what it costs covers what the ceiling covers and what it doesn't.

Related

• Events reference for every event and field.
• The mindset-agent element for the element's error codes.
• Create a session for your users for every create error.