ClawHub

Error Handling

Workflows

Deep error handling workflow—taxonomy, user-visible vs internal errors, retries and idempotency, observability, and supportability. Use when standardizing failure modes across APIs, clients, and async workers.

Install

openclaw skills install error-handling

Error Handling

Consistent errors reduce support load and on-call pain. Design a taxonomy, stable codes, safe user messaging, and operator visibility—without leaking secrets or stack traces to clients.

When to Offer This Workflow

Trigger conditions:

  • Inconsistent HTTP status codes and response bodies
  • Retry storms or duplicate side effects from naive retries
  • Logs that cannot be tied to user-visible failures

Initial offer:

Use six stages: (1) classify errors, (2) map to transport, (3) user messaging, (4) retries & idempotency, (5) observability, (6) client SDKs & DX). Confirm REST/GraphQL/gRPC and sync/async patterns.

Stage 1: Classify Errors

Goal: Distinguish validation, authentication, authorization, not found, conflict, rate limit, dependency failure, and internal bugs.

Exit condition: Table or enum of codes with owning team and meaning.

Stage 2: Map to Transport

Goal: Correct HTTP 4xx/5xx; GraphQL errors with extensions; gRPC status codes; optional RFC 7807 Problem Details for JSON APIs.

Stage 3: User Messaging

Goal: Actionable copy for end users; opaque support reference id; no internal hostnames, SQL fragments, or stack traces in client responses.

Stage 4: Retries & Idempotency

Goal: Retry only safe or idempotent operations; exponential backoff with jitter; align with idempotency keys on writes.

Stage 5: Observability

Goal: Structured logs with error.code, trace_id, user_id (where allowed); metrics by error class; alerts on error-rate SLO burn.

Stage 6: Client SDKs & DX

Goal: Typed errors in SDKs; documented recovery; map codes to user-facing strings in apps consistently.

Final Review Checklist

  • Taxonomy and ownership defined
  • Transport mapping correct and consistent
  • User-safe messages with correlation ids
  • Retry policy matches idempotency story
  • Logs and metrics wired for ops

Tips for Effective Guidance

  • Separate expected validation errors from unexpected 500s in dashboards.
  • Pair with idempotency for write paths and queues.

Handling Deviations

  • Mobile offline: queue with explicit user-visible sync state.
More in Workflows