Error Handling

核心功能为六阶段标准化错误处理：错误分类、传输协议映射、安全用户消息生成、幂等重试配置、可观测性搭建、客户端SDK优化。适用于解决HTTP状态码混乱、重试风暴、日志无法关联用户故障等场景，支持REST/GraphQL/gRPC及同步/异步模式，可减少运维与客服压力。

mike47512

热度 55.46

最近更新 2026-05-11 17:36:11

分类：开发依赖：纯提示词应用场景：API 集成 / DevOps / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add error-handling

Metadata

name: error-handling
description: 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.

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.