error-responses_skill

Overview

This skill enforces safe, structured error responses for APIs. It prevents leaking internal implementation details while providing consistent machine-readable codes and human-friendly messages. Use it to standardize error shapes and improve security and supportability.

How this skill works

The skill recommends creating custom error classes, centralizing error handling in middleware, and logging full error details only server-side. It maps known errors to exact HTTP status codes and returns a minimal ErrorResponse object with code, message, optional details, and a requestId for correlation. Unknown errors are converted to a generic INTERNAL_ERROR response.

When to use it

• Building or refactoring API error handling
• Exposing errors to clients or other services
• Catching exceptions in controllers or middleware
• When error responses are inconsistent across endpoints
• If you or others are tempted to return raw error messages

Best practices

• Never return raw error.message or stack traces to clients
• Log full error context (message, stack, requestId, path) server-side
• Return a consistent ErrorResponse: { error: { code, message, details?, requestId? } }
• Use machine-readable codes (e.g., VALIDATION_ERROR, NOT_FOUND) and stable messages
• Include requestId to correlate client reports with server logs

Example use cases

• API route throws a DB error — return INTERNAL_ERROR with requestId and log full stack
• Validation failures — return VALIDATION_ERROR with details object mapping fields to errors
• Resource lookup misses — return NOT_FOUND with 404 status and clear message
• Auth failures — return 401 or 403 with AUTHENTICATION_ERROR/AUTHORIZATION_ERROR codes
• Upstream failures — map to 502/503 with generic messages and requestId