skills.rest
vTRKA
vTRKACOMMUNITY
Explore all skills by this author →
GitHub

error-envelope-design

Design consistent API error response envelopes with retry semantics and error-code registries.

Updated Apr 27, 2026
Search Tags:#api errors#error envelope#retry semantics#problem+json#graphql unions#grpc status#error-code registry
One-click install
npx skills add https://github.com/vTRKA/supervibe --skill error-envelope-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: error-envelope-design
Source: https://github.com/vTRKA/supervibe/tree/main/skills/error-envelope-design
Command: npx skills add https://github.com/vTRKA/supervibe --skill error-envelope-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents inconsistent API error shapes that cause clients to mis-handle retries, hide root causes, and break batch/multi-resource error semantics.

Core Features & Use Cases

  • Choose the correct envelope per transport: HTTP problem+json, GraphQL unions/error extensions, or gRPC google.rpc.Status with typed details.
  • Define retry and partial-failure contracts: transient vs non-transient behavior, plus per-item error patterns for batch endpoints.
  • Create and centralize an error-code registry: stable, append-only dotted lowercase codes with centralized status/code mapping.
  • Require evidence and verification: blocks completion when sample responses, registry locations, schema/proto/OpenAPI proof, or command/receipt evidence is missing.

Quick Start

Ask your AI tool to design a single, consistent error envelope and error-code registry for your new or drifted API, using evidence from existing endpoints and the project’s transport defaults.

Frequently Asked Questions about error-envelope-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I standardize API error responses to prevent client retry mistakes?▼

Standardize API error responses by designing a consistent envelope that distinguishes transient and non-transient errors, enforcing safe retry semantics and idempotency guidance across endpoints to stop clients from mis-handling retries.

What is the best way to handle batch partial-failure responses in HTTP, GraphQL, and gRPC APIs?▼

Handle batch partial-failure responses by defining per-item error patterns within your API error envelope, applying transport-specific formats like problem+json, GraphQL unions, or gRPC google.rpc.Status to preserve multi-resource error semantics.

How do I create a stable error-code registry for API semantic drift?▼

Create a stable error-code registry using centralized, append-only dotted lowercase codes with strict mapping to HTTP statuses or gRPC codes, preventing semantic drift across endpoints and ensuring consistent client behavior.

Does the error envelope design process require schema or OpenAPI proof?▼

Yes, the error envelope design process requires evidence-backed verification gates that block completion unless you provide sample responses, registry locations, schema/proto definitions, or OpenAPI proof validating the final envelope decisions.

When should I use problem+json versus gRPC status details for API errors?▼

Use problem+json for HTTP/JSON API error envelopes, GraphQL unions or error extensions for GraphQL APIs, and gRPC google.rpc.Status with typed details for gRPC APIs, choosing the correct envelope per transport to ensure consistency.

Why do inconsistent API error shapes break client retry logic?▼

Inconsistent API error shapes break retry logic because clients cannot distinguish transient from non-transient errors, causing inappropriate retry attempts that hide root causes and disrupt batch multi-resource error semantics.

Related Skills

Explore More Software Engineering Skills→
majiayu000majiayu000
258

api-design

Design API contracts for REST, GraphQL, and gRPC contexts.

Community
Advanced
arbazkhan971arbazkhan971
26

api

Design and validate OpenAPI 3.1 specifications for REST, GraphQL, and gRPC services.

Community
Advanced
azmankudusazmankudus

blueprint-webapi

Enforce API contracts using a single OpenAPI 3.1 master specification.

Community
Advanced
mub7865mub7865
1

rest-api-design-and-errors

Standardize REST API resources, URLs, pagination, and RFC 7807 error handling.

Community
Advanced