Agent skill
lang__problem_details
Adds RFC 7807 ProblemDetails error responses with typed error codes in handlers and endpoints. Use when implementing validation, error handling, or API responses. Returns standardized errors with HTTP status mapping.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/lang-problem-details
SKILL.md
All API errors MUST use the Result pattern with ProblemDetails responses. Errors are typed, include machine-readable error codes, and automatically map to appropriate HTTP status codes.
Pattern Overview
Result → Error → ProblemDetails → HTTP Response
- Create
Result.Failure(Error)with error type and code - Call
.ToProblemDetails()to convert to IResult - Framework automatically serializes to RFC 7807 format with status code
Error Types & Status Codes
| Error Type | HTTP Status | Use When |
|---|---|---|
Error.Validation() |
400 Bad Request | Input validation fails, business rules violated |
Error.NotFound() |
404 Not Found | Resource doesn't exist |
Error.Conflict() |
409 Conflict | Resource state conflict (already exists, already deleted) |
Error.Unauthorized() |
401 Unauthorized | Authentication required or failed |
Error.Forbidden() |
403 Forbidden | Authenticated but not authorized |
Error.InternalServerError() |
500 Internal Server Error | Unexpected exceptions |
Error Codes
Error codes follow pattern: ERR_{DOMAIN}_{ERROR_NAME}
Existing domains: Books, Authors, Publishers, Categories, Auth, Cart, Admin, Tenancy, Passkey
Error codes are defined in src/BookStore.Shared/Models/ErrorCodes.cs:
public static class ErrorCodes
{
public static class Books
{
public const string TitleRequired = "ERR_BOOK_TITLE_REQUIRED";
public const string NotFound = "ERR_BOOK_NOT_FOUND";
// ... more codes
}
}
Steps
-
Identify Error Type
- Determine which Error factory method matches your scenario
- Choose appropriate HTTP status code mapping
-
Find or Add Error Code
- Check
ErrorCodes.<Domain>for existing code - Add new code if needed following naming pattern
- Template: See templates/ErrorCodes.Domain.cs
- Check
-
Create Error Result
- Use
Result.Failure(Error.<Type>(code, message)) - Include helpful message for developers/UI
- Return
.ToProblemDetails()
- Use
-
Add Logging (Optional but Recommended)
- Use
/lang__logger_messagefor structured logging - Log before returning error for diagnostics
- Use
Examples
Validation Error (400):
if (string.IsNullOrWhiteSpace(command.Title))
{
Log.Books.TitleRequired(logger, command.Id);
return Result.Failure(
Error.Validation(
ErrorCodes.Books.TitleRequired,
"Book title is required"
)).ToProblemDetails();
}
Not Found Error (404):
var book = await session.LoadAsync<BookDetails>(id);
if (book is null)
{
Log.Books.BookNotFound(logger, id);
return Result.Failure(
Error.NotFound(
ErrorCodes.Books.BookNotFound,
"Book not found"
)).ToProblemDetails();
}
Conflict Error (409):
if (aggregate.IsDeleted)
{
return Result.Failure(
Error.Conflict(
ErrorCodes.Books.AlreadyDeleted,
"Cannot update a deleted book"
)).ToProblemDetails();
}
Unauthorized Error (401):
if (userId is null)
{
return Result.Failure(
Error.Unauthorized(
ErrorCodes.Auth.InvalidToken,
"User not authenticated"
)).ToProblemDetails();
}
From Aggregate (Business Logic):
var eventResult = BookAggregate.CreateEvent(/* ... */);
if (eventResult.IsFailure)
{
return eventResult.ToProblemDetails();
}
// Use the event
session.Events.StartStream<BookAggregate>(id, eventResult.Value);
Internal Server Error (500):
catch (Exception ex)
{
Log.Books.UnexpectedError(logger, ex);
return Result.Failure(
Error.InternalServerError(
ErrorCodes.Books.InternalError,
$"An unexpected error occurred: {ex.Message}"
)).ToProblemDetails();
}
Response Format
ProblemDetails JSON response includes:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Book title is required",
"error": "ERR_BOOK_TITLE_REQUIRED"
}
type: RFC 7231 referencetitle: Human-readable status namestatus: HTTP status codedetail: Error messageerror: Machine-readable error code (in extensions)
Common Patterns
Multiple Validations:
// Check culture codes
if (!CultureValidator.IsValidCultureCode(command.Language))
{
return Result.Failure(
Error.Validation(
ErrorCodes.Books.LanguageInvalid,
"Invalid language code"
)).ToProblemDetails();
}
// Check translations
if (!CultureValidator.ValidateTranslations(command.Translations, out var invalidCodes))
{
return Result.Failure(
Error.Validation(
ErrorCodes.Books.TranslationLanguageInvalid,
$"Invalid language codes: {string.Join(", ", invalidCodes)}"
)).ToProblemDetails();
}
Aggregate Validation:
// Let aggregate handle business rules
var eventResult = aggregate.UpdateEvent(command.Name);
if (eventResult.IsFailure)
{
// Aggregate already created appropriate Error type
return eventResult.ToProblemDetails();
}
session.Events.Append(id, eventResult.Value);
Version Conflict:
var expectedVersion = ETagHelper.ParseETag(command.ETag);
if (expectedVersion.HasValue && aggregate.Version != expectedVersion.Value)
{
return ETagHelper.PreconditionFailed(); // Returns 412 Precondition Failed
}
Related Skills
Prerequisites:
- Understanding of Result pattern in
src/BookStore.Shared/Models/Result.cs
See Also:
/lang__logger_message- Add logging alongside error handling/wolverine__create_operation- Uses error handling in create handlers/wolverine__update_operation- Uses error handling in update handlers/wolverine__delete_operation- Uses error handling in delete handlerssrc/BookStore.Shared/Models/Error.cs- Error factory methodssrc/BookStore.Shared/Models/ErrorCodes.cs- All error codessrc/BookStore.ApiService/Infrastructure/Extensions/ResultExtensions.cs- ToProblemDetails implementation
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?