From supervibe
Use WHEN designing API error responses TO pick a consistent envelope (HTTP problem details problem+json / GraphQL union / gRPC status), define retry semantics, partial failure shapes. Triggers: 'error envelope', 'API ошибки формат', 'формат ошибок', 'problem+json'.
npx claudepluginhub vtrka/supervibe --plugin supervibeThis skill is limited to using the following tools:
WHEN designing the first endpoint of a new API. WHEN extending an API whose error shape is inconsistent across endpoints. WHEN clients keep parsing error strings to decide whether to retry. WHEN a 500 response actually means a validation failure — i.e. the envelope has lost its semantics.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
WHEN designing the first endpoint of a new API. WHEN extending an API whose error shape is inconsistent across endpoints. WHEN clients keep parsing error strings to decide whether to retry. WHEN a 500 response actually means a validation failure — i.e. the envelope has lost its semantics.
The skill produces a single answer for the project: one envelope shape, one error-code registry, one retry contract, one partial-failure pattern. Mixed envelopes are the most common cause of unreliable client retries.
Follow docs/references/skill-expert-operating-standard.md: start from source of truth, preserve retrieval evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.
grep -rE "ErrorCode|errorCode|code:\s*['\"]" src/. The result is the seed of the registry.Transport?
HTTP/JSON → HTTP problem details problem+json (type, title, status, detail, instance, code, errors[])
GraphQL → Errors-as-data via union types on mutations; reserve top-level `errors[]` for transport faults
gRPC → google.rpc.Status with typed details (ErrorInfo, BadRequest, RetryInfo, QuotaFailure)
Is the failure transient?
YES (5xx, 429, UNAVAILABLE, ABORTED) → MUST include Retry-After / RetryInfo + idempotency guidance
NO (4xx, FAILED_PRECONDITION, INVALID_ARGUMENT) → MUST NOT advertise retry; clients that retry are buggy
Is the operation a batch / multi-resource call?
YES → partial failure shape: per-item status, never an all-or-nothing 500
NO → standard envelope
Is the error machine-actionable by the client?
YES → stable code from the registry (e.g. `payment.card_declined`)
NO → generic code (`internal_error`) + correlation id, never a free-form string the client must parse
auth.token_expired, billing.insufficient_funds). Store in a single file (TypeScript enum, Go const block, Java enum, proto enum). Codes are append-only — never reuse, never silently rename.Retry-After (seconds) or google.rpc.RetryInfo. Document the retry algorithm clients should use (exponential backoff with jitter, max attempts) in the style guide. Non-transient codes MUST omit retry hints.Idempotency-Key, define what a replay returns (the original response, not a fresh one) and how long the key is honoured. The key contract is part of the error envelope spec.Status.OK with details) with a per-item array { id, status, error? }. Never collapse a 1-of-100 failure into a 500.code plus a correlationId. Stack traces, SQL fragments, and internal hostnames are logged server-side only.Deprecation / Sunset headers (HTTP) or a deprecated flag in the registry. Maintain old codes for at least one major version with monitoring on residual usage.supervibe:confidence-scoring with artifact-type=agent-output; ≥9 required to mark this skill complete.Envelope: <HTTP problem details | GraphQL union | google.rpc.Status>
Required fields: <list>
Registry location: <path>
Code naming rule: <regex / pattern>
Status mapping: <code → http/grpc status> (centralised, not at throw sites)
Retry contract:
Transient codes: <list> + Retry-After source
Non-transient codes: <list> (no retry hints)
Client algorithm: <expo backoff parameters>
Idempotency:
Header / field: <Idempotency-Key>
Replay window: <seconds>
Replay shape: <verbatim original response>
Partial failure shape: <schema for per-item status>
Internal data leak rules: <forbidden fields list>
Deprecation: <Sunset header + monitoring metric>
error.message to branch logic; any wording change is a breaking change.{error: "..."} here, {message: "..."} there, {detail, code} elsewhere; clients write a switch per endpoint.supervibe:test-strategy — contract tests assert the envelope at the API boundary.supervibe:auth-flow-design — auth errors must use the same envelope, not a bespoke one.supervibe:prd — capture envelope choice as a PRD decision section; future API versions inherit it.supervibe:incident-response — correlationId from the envelope is the bridge to logs/traces.