ReliabilityGuide5 min

Handle tool failures without breaking UX

A resilient design pattern for model workflows that depend on APIs, databases, and external services.

Real example

Example: CRM lookup fails during account summary generation

A support assistant can summarize tickets, usage, and billing status. The billing API times out during one request.

Return a partial result that clearly marks billing as unavailable, disable billing-sensitive recommendations, and offer retry or human escalation. Log the internal diagnostic code separately.

The user still receives useful support context without trusting an incomplete recommendation.

Tutorial path

How to implement it

Step 01

Classify tools by read-only, idempotent write, destructive write, and external send.

Step 02

Return structured errors with user-safe messages and internal diagnostic codes.

Step 03

Let the model continue with partial data only when the product can explain the limitation.

Step 04

Provide retry, manual fallback, or escalation actions in the UI.

Step 05

Alert only on failures that affect users or indicate systemic breakage.

Checklist

Ready when these are true

Tool risk classified

Structured error shape

Bounded retries

Manual fallback

User-safe error copy

Field notes

What matters in practice

Tool failures are expected production states, not exceptional surprises.

The user should know what completed, what failed, and what they can do next.

Retries should be bounded and tied to idempotent operations.

Avoid these mistakes

Common failure modes

Do not let the model pretend the failed tool returned data.

Do not show raw internal errors to users.

Do not retry non-idempotent writes automatically.

Practical tip

Partial results are fine when the UI names what is missing and blocks decisions that depend on it.

Apply this to a build