playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / backend-api-responses

backend-api-responses skill

/.claude/skills/backend-api-responses

This skill helps you standardize API responses with consistent envelopes, status codes, and error formats across controllers and serializers.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill backend-api-responses

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

Files (1)
SKILL.md
2.0 KB
---
name: Backend API Responses
description: Structure API responses with consistent envelopes, appropriate HTTP status codes, and standardized error formats. Use this skill when implementing response handlers, formatting API response data, creating error response structures, implementing validation error responses, setting up pagination response formats, defining response DTOs or serializers, implementing HTTP status code logic, creating response middleware or interceptors, formatting success and error response envelopes, sanitizing response data to prevent sensitive data leakage, implementing field-level validation error responses, or working with response transformation logic. Use when writing controller return statements, response serializers, error handlers, or any code that formats and returns data to API clients.
---

## When to use this skill

- When implementing response handlers or formatters
- When creating or updating error response structures
- When implementing validation error responses with field-level details
- When setting up pagination response formats (limit/offset or cursor-based)
- When defining response DTOs, serializers, or data transfer objects
- When implementing HTTP status code selection logic
- When creating response middleware, interceptors, or transformers
- When formatting success response envelopes
- When sanitizing response data to prevent sensitive information leakage
- When implementing consistent error code and message formats
- When working with controller return statements or response builders
- When creating response helper functions or utilities
- When removing stack traces or internal details from production responses

# Backend API Responses

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle backend API responses.

## Instructions

For details, refer to the information provided in this file:
[backend API responses](../../../agent-os/standards/backend/api/responses.md)

Overview

This skill enforces consistent, safe, and developer-friendly API response patterns for TypeScript backends. It defines standard envelopes for success and error responses, maps domain conditions to correct HTTP status codes, and removes internal details from production output. Use it to make responses predictable for clients and easier to test and maintain.

How this skill works

The skill inspects controller return values and response middleware to wrap data in a standardized envelope containing metadata, status, and payload. It applies rules for HTTP status selection, formats validation and field-level errors, structures pagination metadata, and strips sensitive fields before sending. It can be used to implement serializers, DTOs, interceptors, or helper functions that produce these consistent outputs.

When to use it

  • Implementing response handlers or formatters
  • Creating or updating error response structures
  • Implementing validation error responses with field-level details
  • Setting up pagination response formats (limit/offset or cursor)
  • Defining response DTOs, serializers, or data transfer objects
  • Creating response middleware, interceptors, or transformers

Best practices

  • Return a thin envelope: { success, status, data, error, meta } to keep client parsing predictable
  • Map domain outcomes to precise HTTP statuses (e.g., 200, 201, 204, 400, 401, 403, 404, 409, 422, 500) and avoid overloading 200 for errors
  • Provide structured error objects with code, message, and optional fieldErrors for validation failures
  • Include pagination meta (total, limit, offset or cursor) separate from data list to simplify client handling
  • Sanitize responses: remove passwords, tokens, stack traces, and internal IDs before sending to clients
  • Keep environment-aware details: include debug information only in non-production environments and never expose stack traces in production

Example use cases

  • Controller returns: wrap entity in success envelope with 201 after create
  • Validation pipeline: return 422 with fieldErrors array containing path, message, and rejectedValue
  • Pagination endpoint: return { data: [...], meta: { total, limit, offset } } for list endpoints
  • Error handler middleware: convert thrown exceptions into { error: { code, message } } and set appropriate status
  • Serialization: use DTO serializers to drop sensitive fields and shape response payloads for clients

FAQ

How should I represent validation errors?

Use a 422 status and include a fieldErrors array with objects containing field, message, and optionally rejectedValue to let clients display specific feedback.

When should I use 204 No Content?

Return 204 when an operation succeeds but there is no resource body to return, such as successful deletion; do not include a response body with 204.