status-code-decision-matrix

name	status-code-decision-matrix
description	Choose HTTP status codes and response payload behavior for ASP.NET Core minimal APIs. Use for success and error branch semantics, problem details, conflicts, and compatibility exceptions.
argument-hint	Describe the operation type, expected success result, known failure modes, and any client-compatibility constraints.

Status Code Decision Matrix

When to Use

• Endpoint behavior design or review in src/backend
• Inconsistent status code handling across endpoints
• PR review focused on HTTP semantics

Quick Checklist

1. Classify operation type and expected outcomes.
2. Assign canonical success status.
3. Assign specific 4xx/5xx statuses per failure cause.
4. Document and justify compatibility exceptions.

Deep Workflow

1. Classify operation type: read, create, replace, partial update, delete, command/action.
2. Enumerate all outcomes: success, validation failure, authz/authn failure, not found, conflict, transient dependency failure.
3. Select success status:
   • Read single/list: 200
   • Create: 201 with location when resource URI is available
   • Delete with no body: 204
   • Command accepted async: 202
4. Select client-error status:
   • Validation/input errors: 400 with problem details
   • Authn/authz: 401/403
   • Missing resource: