api-error-handling
API Error Handling
Scope Boundaries
- Use when API error taxonomy, response schemas, and status mapping are being created or changed.
- Use proactively when failure handling is implicit, inconsistent, or incident learning needs to be codified in the contract.
- Use proactively when error payload or status-mapping diffs are detected without explicit retry/backoff policy.
- Use when retry/backoff behavior affects client correctness or operational stability.
- Do not use for transport-independent incident handling policy; use
incident-postmortemor runbook skills. - Do not use for storage internals; use
db-*.
Goal
Deliver machine-actionable error contracts that are stable across versions.
Shared API Contract (Canonical)
- Use
../api-design-rest/references/api-governance-contract.mdas the canonical contract. - Optional consistency checks (only if your repository enforces manifest validation):
python3 ../api-design-rest/scripts/validate_api_contract.py --manifest <path/to/manifest.json>
- Reuse valid API error templates in
../api-design-rest/assets/. - Use threshold derivation reference:
../api-design-rest/references/threshold-derivation-framework.md
- Do not add local error-ID formats or local lifecycle variants.
Implementation Templates
- Error catalog template:
../api-design-rest/assets/api-error-catalog-template.yaml
Inputs
- Existing API status and error behavior
- Consumer retry and fallback assumptions
- Security/privacy constraints for error payload fields
Outputs
- Error taxonomy with stable error codes and ownership
- Status-to-error mapping table by scenario
- Standard error payload schema with trace correlation and retry semantics
Workflow
- Define error categories (validation, authorization, conflict, dependency, internal).
- Map each category to transport status and retry guidance (
retryable, backoff expectations). - Define stable error code registry and deprecation policy for retired codes.
- Define payload fields for client actionability and operator triage (including trace identifiers).
- Align error behavior across sync/async/realtime transports when a domain is multi-transport.
- Verify contract behavior with representative failure scenarios.
- Validate artifact compliance against the canonical API contract.
Quality Gates
- Error codes are stable, unique, and documented with owner.
- Status mapping is deterministic and consistent across endpoints.
- Error payload excludes sensitive internal details but preserves debugging context.
- Operational runbooks and alert correlations reference the published error model.
Failure Handling
- Stop when clients cannot determine retry vs non-retry behavior from contract.
- Stop when status mapping varies for the same error class without explicit policy.
- Escalate when compatibility impact on existing consumers is unresolved.
More from kentoshimizu/sw-agent-skills
graph-algorithms
Graph algorithm workflow for modeling entities/relations and selecting traversal, path, ordering, or flow strategies. Use when correctness or performance depends on graph representation and algorithm choice; do not use for schema-only modeling or deployment topology planning.
14bash-style-guide
Style, review, and refactoring standards for Bash shell scripting. Trigger when `.sh` files, files with `#!/usr/bin/env bash` or `#!/bin/bash`, or CI workflow blocks with `shell: bash` are created, modified, or reviewed and Bash-specific quality controls (quoting safety, error handling, portability, readability) must be enforced. Do not use for generic POSIX `sh`, PowerShell, or language-specific application style rules. In multi-language pull requests, run together with other applicable `*-style-guide` skills.
11architecture-clean-architecture
Clean Architecture workflow for enforcing dependency direction, stable domain boundaries, and use-case-centered application design. Use when teams must separate business rules from frameworks and delivery mechanisms; do not use for isolated module cleanup without boundary implications.
11powershell-style-guide
Style, review, and refactoring standards for PowerShell scripting. Trigger when `.ps1`, `.psm1`, `.psd1` files, or CI workflow blocks with `shell: pwsh` or `shell: powershell` are created, modified, or reviewed and PowerShell-specific quality controls (error handling, parameter validation, readability, operational safety) must be enforced. Do not use for Bash, generic POSIX `sh`, or language-specific application style rules. In multi-language pull requests, run together with other applicable `*-style-guide` skills.
10github-codeowners-management
Govern CODEOWNERS rules so review routing reflects real ownership and risk boundaries on GitHub. Use when repository ownership mapping or mandatory reviewer rules must be defined, updated, or audited; do not use for non-GitHub runtime architecture or data-layer design.
9security-authentication
Security workflow for authentication architecture, credential lifecycle, and session/token assurance. Use when login, identity proofing, MFA, or session security decisions are required; do not use for authorization policy design or non-security quality tuning.
9