Adopt `422 Unprocessable Entity` for payload validation errors

[nanotaboada]

Problem

Field validation failures currently return 400 Bad Request, which conflates two distinct error categories:

• 400 Bad Request — the request is malformed (unparseable JSON, wrong Content-Type)
• 422 Unprocessable Entity — the request is syntactically valid but fails business/field validation rules

Proposed Solution

Return 422 Unprocessable Entity for field validation failures and reserve 400 Bad Request for genuinely malformed requests.

TypedResults.ValidationProblem() already produces a ProblemDetails-compatible body — the change is to emit 422 instead of 400 as its status code.

Acceptance Criteria

• Field validation failures return 422 Unprocessable Entity (RFC 9457 problem details)
• 400 Bad Request is reserved for malformed requests (unparseable JSON, wrong Content-Type)
• Swagger/OpenAPI docs updated to declare 422 instead of 400 for validation responses
• Tests updated to assert the new status code
• All existing tests continue to pass
• CHANGELOG.md updated

References

• RFC 4918 — 422 Unprocessable Entity
• RFC 9457 — Problem Details for HTTP APIs

[coderabbitai]

🔗 Related PRs

#321 - feat: add global exception handling middleware with RFC 7807 support [merged]
#420 - refactor(api)!: add /squadNumber/ path segment to routes [merged]
#426 - fix(validators): scope BeUniqueSquadNumber to "Create" rule set (#424) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Explicitly pass statusCode: StatusCodes.Status422UnprocessableEntity to all TypedResults.ValidationProblem() calls to ensure correct response codes regardless of framework defaults
• Update Swagger metadata via [ProducesResponseType] attributes and XML doc comments to accurately document the 422 response for validation errors
• Preserve 400 status code for the squad number mismatch error in PutAsync since this represents a semantically invalid request rather than a field validation failure
• Update both unit and integration tests to assert the new 422 status code while leaving the mismatch test unchanged

Implementation Steps

Phase 1: Update Application Code

Update the controller and middleware to return 422 for validation failures while preserving 400 for genuinely malformed requests like the squad number route/body mismatch in PUT.

Task 1: Update Controller Validation Responses

Modify PlayerController.cs to explicitly return 422 for field validation errors and update associated Swagger metadata.

• In PostAsync, add explicit statusCode: StatusCodes.Status422UnprocessableEntity parameter to the TypedResults.ValidationProblem() call
• Change the [ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)] attribute to use Status422UnprocessableEntity
• Update the XML doc comment from <response code="400">Bad Request</response> to <response code="422">Unprocessable Entity</response>
• In PutAsync, add explicit statusCode: StatusCodes.Status422UnprocessableEntity parameter to the TypedResults.ValidationProblem() call
• Add a new [ProducesResponseType<ProblemDetails>(StatusCodes.Status422UnprocessableEntity)] attribute for validation errors while keeping the existing 400 attribute for the squad number mismatch case
• Update PutAsync XML docs to distinguish between the two error cases: 400 for route/body mismatch, 422 for validation errors

Task 2: Update Exception Middleware

Modify ExceptionMiddleware.cs to return 422 for ValidationException as a safety net for any uncaught validation exceptions.

• In the MapExceptionToStatusCode method, change the ValidationException case from StatusCodes.Status400BadRequest to StatusCodes.Status422UnprocessableEntity
• Keep the title as "Validation Error" to maintain semantic clarity

🤖 Prompt for AI agents

Update `PlayerController.cs` and `ExceptionMiddleware.cs` to return HTTP 422 for
validation failures instead of 400, while preserving 400 for the squad number
mismatch case in PUT.

**`PlayerController.cs` — `PostAsync`:**
- Add explicit `statusCode: StatusCodes.Status422UnprocessableEntity` parameter
to the `TypedResults.ValidationProblem()` call
- Change
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)]` to
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status422UnprocessableEntity)]`
- Update the XML doc comment from `<response code="400">Bad Request</response>`
to `<response code="422">Unprocessable Entity</response>`

**`PlayerController.cs` — `PutAsync`:**
- Add explicit `statusCode: StatusCodes.Status422UnprocessableEntity` parameter
to the `TypedResults.ValidationProblem()` call
- Add a new
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status422UnprocessableEntity)]`
attribute for validation errors
- Keep the existing
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)]`
attribute for the squad number mismatch case
- Update the XML doc comments to distinguish the two error cases: 400 for
route/body mismatch, 422 for validation errors

**`ExceptionMiddleware.cs`:**
- In the `MapExceptionToStatusCode` method, change the `ValidationException`
case from returning `StatusCodes.Status400BadRequest` to
`StatusCodes.Status422UnprocessableEntity`
- Keep the title as "Validation Error"

Phase 2: Update Tests

Update all test assertions that verify validation error status codes to expect 422 instead of 400, while preserving assertions for the squad number mismatch case which should remain 400.

Task 1: Update Unit Tests

Modify PlayerControllerTests.cs to assert 422 for validation error scenarios.

• Rename Post_Players_ValidationError_Returns400BadRequest to Post_Players_ValidationError_Returns422UnprocessableEntity
• Update the status code assertion from StatusCodes.Status400BadRequest to StatusCodes.Status422UnprocessableEntity
• Rename Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest to Put_PlayerBySquadNumber_ValidationError_Returns422UnprocessableEntity
• Update the status code assertion from StatusCodes.Status400BadRequest to StatusCodes.Status422UnprocessableEntity
• Leave Put_PlayerBySquadNumber_SquadNumberMismatch_Returns400BadRequest unchanged as this is a semantic 400 error, not a validation error

Task 2: Update Integration Tests

Modify PlayerWebApplicationTests.cs to assert 422 for validation error HTTP responses.

• Rename Post_Players_ValidationError_Returns400BadRequest to Post_Players_ValidationError_Returns422UnprocessableEntity
• Change HttpStatusCode.BadRequest assertion to HttpStatusCode.UnprocessableEntity
• Change StatusCodes.Status400BadRequest assertion to StatusCodes.Status422UnprocessableEntity
• Rename Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest to Put_PlayerBySquadNumber_ValidationError_Returns422UnprocessableEntity
• Apply the same status code assertion changes
• Leave Put_PlayerBySquadNumber_SquadNumberMismatch_Returns400BadRequest unchanged as this remains a 400 error

🤖 Prompt for AI agents

Update test files to expect HTTP 422 for validation error scenarios, while
leaving the squad number mismatch test assertions at 400.

**`PlayerControllerTests.cs`:**
- Rename `Post_Players_ValidationError_Returns400BadRequest` →
`Post_Players_ValidationError_Returns422UnprocessableEntity` and update its
status code assertion from `StatusCodes.Status400BadRequest` to
`StatusCodes.Status422UnprocessableEntity`
- Rename `Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest` →
`Put_PlayerBySquadNumber_ValidationError_Returns422UnprocessableEntity` and
update its status code assertion from `StatusCodes.Status400BadRequest` to
`StatusCodes.Status422UnprocessableEntity`
- Do NOT modify
`Put_PlayerBySquadNumber_SquadNumberMismatch_Returns400BadRequest`

**`PlayerWebApplicationTests.cs`:**
- Rename `Post_Players_ValidationError_Returns400BadRequest` →
`Post_Players_ValidationError_Returns422UnprocessableEntity`; change
`HttpStatusCode.BadRequest` to `HttpStatusCode.UnprocessableEntity` and
`StatusCodes.Status400BadRequest` to `StatusCodes.Status422UnprocessableEntity`
- Rename `Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest` →
`Put_PlayerBySquadNumber_ValidationError_Returns422UnprocessableEntity` and
apply the same status code assertion changes
- Do NOT modify
`Put_PlayerBySquadNumber_SquadNumberMismatch_Returns400BadRequest`

Phase 3: Update Documentation

Document the breaking change in the changelog for API consumers.

Update CHANGELOG.md

Add an entry documenting the status code change for validation errors.

• Add a new version entry or update the unreleased section
• Document the change from 400 to 422 for field validation errors under a "Changed" or "Breaking Changes" heading
• Reference RFC 4918 (422 Unprocessable Entity) and RFC 9457 (Problem Details) as rationale
• Note that 400 Bad Request is now reserved for malformed requests (unparseable JSON, wrong Content-Type)

🤖 Prompt for AI agents

Update `CHANGELOG.md` to document the breaking status code change for API
consumers.

- Add a new version entry or update the existing unreleased section
- Under a "Changed" or "Breaking Changes" heading, document that field
validation errors now return 422 instead of 400
- Reference RFC 4918 (422 Unprocessable Entity) and RFC 9457 (Problem Details)
as rationale for the change
- Note that 400 Bad Request is now reserved for malformed requests (e.g.
unparseable JSON, wrong Content-Type)

Research

The project follows a traditional layered ASP.NET Core Web API architecture with a single PlayerController that uses FluentValidation for request validation. Validation is performed manually in controller actions via validator.ValidateAsync() with named rule sets, returning TypedResults.ValidationProblem() on failure. A global ExceptionMiddleware provides fallback handling for uncaught ValidationException errors. Swagger documentation is configured via [ProducesResponseType] attributes and XML doc comments. Tests are split between unit tests (directly testing controller IResult return types) and integration tests (using WebApplicationFactory to test HTTP responses).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update `PlayerController.cs` and `ExceptionMiddleware.cs` to return HTTP 422 for
validation failures instead of 400, while preserving 400 for the squad number
mismatch case in PUT.

**`PlayerController.cs` — `PostAsync`:**
- Add explicit `statusCode: StatusCodes.Status422UnprocessableEntity` parameter
to the `TypedResults.ValidationProblem()` call
- Change
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)]` to
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status422UnprocessableEntity)]`
- Update the XML doc comment from `<response code="400">Bad Request</response>`
to `<response code="422">Unprocessable Entity</response>`

**`PlayerController.cs` — `PutAsync`:**
- Add explicit `statusCode: StatusCodes.Status422UnprocessableEntity` parameter
to the `TypedResults.ValidationProblem()` call
- Add a new
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status422UnprocessableEntity)]`
attribute for validation errors
- Keep the existing
`[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest)]`
attribute for the squad number mismatch case
- Update the XML doc comments to distinguish the two error cases: 400 for
route/body mismatch, 422 for validation errors

**`ExceptionMiddleware.cs`:**
- In the `MapExceptionToStatusCode` method, change the `ValidationException`
case from returning `StatusCodes.Status400BadRequest` to
`StatusCodes.Status422UnprocessableEntity`
- Keep the title as "Validation Error"
===============================================================================

Task: 2

Update test files to expect HTTP 422 for validation error scenarios, while
leaving the squad number mismatch test assertions at 400.

**`PlayerControllerTests.cs`:**
- Rename `Post_Players_ValidationError_Returns400BadRequest` →
`Post_Players_ValidationError_Returns422UnprocessableEntity` and update its
status code assertion from `StatusCodes.Status400BadRequest` to
`StatusCodes.Status422UnprocessableEntity`
- Rename `Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest` →
`Put_PlayerBySquadNumber_ValidationError_Returns422UnprocessableEntity` and
update its status code assertion from `StatusCodes.Status400BadRequest` to
`StatusCodes.Status422UnprocessableEntity`
- Do NOT modify
`Put_PlayerBySquadNumber_SquadNumberMismatch_Returns400BadRequest`

**`PlayerWebApplicationTests.cs`:**
- Rename `Post_Players_ValidationError_Returns400BadRequest` →
`Post_Players_ValidationError_Returns422UnprocessableEntity`; change
`HttpStatusCode.BadRequest` to `HttpStatusCode.UnprocessableEntity` and
`StatusCodes.Status400BadRequest` to `StatusCodes.Status422UnprocessableEntity`
- Rename `Put_PlayerBySquadNumber_ValidationError_Returns400BadRequest` →
`Put_PlayerBySquadNumber_ValidationError_Returns422UnprocessableEntity` and
apply the same status code assertion changes
- Do NOT modify
`Put_PlayerBySquadNumber_SquadNumberMismatch_Returns400BadRequest`
===============================================================================

Task: 3

Update `CHANGELOG.md` to document the breaking status code change for API
consumers.

- Add a new version entry or update the existing unreleased section
- Under a "Changed" or "Breaking Changes" heading, document that field
validation errors now return 422 instead of 400
- Reference RFC 4918 (422 Unprocessable Entity) and RFC 9457 (Problem Details)
as rationale for the change
- Note that 400 Bad Request is now reserved for malformed requests (e.g.
unparseable JSON, wrong Content-Type)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!