playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / handling-api-errors

handling-api-errors skill

/plugins/api-development/api-error-handler/skills/handling-api-errors

This skill helps you implement standardized API error handling with proper status codes and consistent error responses across endpoints.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill handling-api-errors

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.4 KB
---
name: handling-api-errors
description: |
  Implement standardized error handling with proper HTTP status codes and error responses.
  Use when implementing standardized error handling.
  Trigger with phrases like "add error handling", "standardize errors", or "implement error responses".
  
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(api:error-*)
version: 1.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---

# Handling Api Errors

## Overview


This skill provides automated assistance for api error handler tasks.
This skill provides automated assistance for the described functionality.

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies
1. Generate boilerplate code using Bash(api:error-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models
1. Write integration tests covering all endpoints


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output

- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables
- OpenAPI 3.0 specification with complete endpoint definitions

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
- OpenAPI Specification 3.0+ for API documentation

Overview

This skill implements standardized API error handling with clear HTTP status codes and consistent JSON error responses. It provides patterns, middleware hooks, and response schemas so services return predictable errors for clients and automated tests. The goal is safer, debuggable APIs and easier integration across services.

How this skill works

The skill inspects API specs and route handlers, then adds centralized error middleware and typed error classes. It enforces status codes, error codes, user-friendly messages, and optional debug details based on environment. It can scaffold handlers, validation layers, and OpenAPI error responses to keep documentation and runtime behavior aligned.

When to use it

  • Adding error handling to new APIs
  • Standardizing responses across microservices
  • Improving client-side error parsing and retries
  • Ensuring compliance with API contracts and OpenAPI specs
  • Adding observability and structured error logs

Best practices

  • Use a small set of canonical error types (e.g., ValidationError, NotFoundError, AuthError, ServerError) with numeric codes and stable strings
  • Return proper HTTP status codes (4xx for client errors, 5xx for server errors) and avoid leaking internal details in production
  • Include an error id or request id in responses for tracing and correlate with logs
  • Keep error schema consistent: {code, message, details?, request_id?} and document it in OpenAPI
  • Validate input early and translate validation failures into structured errors rather than stack traces
  • Write integration tests that assert status codes and error payload shapes

Example use cases

  • Add middleware that converts exceptions into JSON responses and maps exceptions to status codes
  • Standardize validation failures across endpoints with a common ValidationError response shape
  • Implement an error id header and include it in logs to speed debugging across services
  • Update OpenAPI docs to include standardized error responses for every endpoint
  • Create a CLI scaffold command to add error handling boilerplate to new endpoints

FAQ

How do I avoid exposing internal stack traces in production?

Strip stack traces from client responses and log full details server-side. Use environment checks to include debug details only in non-production environments.

What error schema should I pick?

Use a minimal, stable schema such as {code: string, message: string, details?: object, request_id?: string}. Keep codes stable and machine-friendly, and document them in OpenAPI.

How to map framework-specific errors to standardized responses?

Create adapter middleware that catches framework errors, maps them to canonical error classes, and then serializes them using the shared error schema. Add tests for each mapping.