error-model-validation-architect

Define machine-readable API error contracts for Kotlin and Spring services.

14|1|Updated Mar 6, 2026
One-click install
npx skills add https://github.com/Kotlin/kotlin-backend-agent-skills --skill error-model-validation-architect
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: error-model-validation-architect
Source: https://github.com/Kotlin/kotlin-backend-agent-skills/tree/main/.agents/skills/error-model-validation-architect
Command: npx skills add https://github.com/Kotlin/kotlin-backend-agent-skills --skill error-model-validation-architect

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design and implement consistent API validation and error-handling behavior for Kotlin plus Spring services. Use when defining error payloads, mapping framework and domain exceptions, standardizing HTTP status codes, adding @ControllerAdvice, preventing internal-detail leakage, or ensuring clients can rely on stable machine-readable error semantics across endpoints.

Core Features & Use Cases

  • Establish a stable error taxonomy covering malformed input, not found, conflicts, authentication, authorization, and downstream failures.
  • Map errors to explicit HTTP status codes and a machine-readable payload with a consistent contract.
  • Provide a centralized error handling strategy using a ControllerAdvice and documented guidelines for developers.
  • Use cases include API design-time contracts, auditing and observability of errors, and safe error responses for public endpoints.

Quick Start

Define and implement a stable, machine-readable API error contract for a Kotlin + Spring service, including error taxonomy, status mappings, and a ControllerAdvice-based handler.

Frequently Asked Questions about error-model-validation-architect

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I standardize API error responses in Spring to prevent leaking internal details?

Standardize API error responses in Spring by establishing a consistent error contract using ControllerAdvice to map exceptions. This ensures clients receive stable, machine-readable payloads without internal-detail leakage, covering malformed input, conflicts, and downstream failures.

What is the best way to map domain exceptions to HTTP status codes in Kotlin?

Map domain exceptions to HTTP status codes in Kotlin by applying a centralized ControllerAdvice strategy. This separates transport and domain validation, assigning explicit status codes and a machine-readable payload with error codes and correlation IDs for reliable client semantics.

How do I design a machine-readable error payload for REST endpoints?

Design a machine-readable error payload for REST endpoints by defining a stable error taxonomy. Include explicit error codes, correlation IDs, and nested field paths to support API design-time contracts, observability, and safe error responses for public endpoints.

Can I use ControllerAdvice to handle validation errors and downstream failures uniformly?

Yes, you can use ControllerAdvice to handle validation errors and downstream failures uniformly. It provides a centralized error handling strategy that maps malformed input, not found, authentication, and authorization errors to standardized HTTP status codes and a consistent contract.

When do I need to separate transport and domain validation in backend services?

Separate transport and domain validation in backend services when you need predictable API errors and stable client contracts. This separation ensures framework and domain exceptions map correctly to HTTP status codes without exposing sensitive internal application logic.

How do I add correlation IDs to API error handling in Spring?

Add correlation IDs to API error handling in Spring by including them in a standardized, machine-readable error payload. This supports auditing and observability of errors across endpoints, ensuring clients and logs can trace specific failures through the system.