Six Requests a Minimal API Should Refuse, and Their Status Codes

How should a warehouse order API refuse illegal state changes, short stock, stale ETag writes and malformed JSON? The author builds a pick-pack-ship demo on .NET 10 Minimal APIs and EF Core 10, mapping each refusal to a specific status code, such as 409, 412 and 400. He also explains why an exact retry should return 200 instead of an error. A useful guide for anyone designing workflow endpoints.

Key points

• An illegal state transition returns 409, and the problem details include allowedActions for the current status.
• Stock is checked for every line before any reservation is written; the error reports sku, requested and available.
• A stale If-Match header gets 412 Precondition Failed, which tells the client to reload rather than treat it as a conflict.
• An exact retry of the same ship request returns 200 with no write, while a different tracking number gets 409.
• Use int? with [Required] on quantity fields so a missing value becomes a 400 instead of binding as 0.
• Malformed JSON should return 400; use StatusCodeSelector in UseExceptionHandler to keep BadHttpRequestException status codes.

This article walks through six requests a pick-pack-ship order API should refuse, and the HTTP status code each one should get. The order lifecycle is modeled as a small state machine. An illegal transition returns 409, and the problem response lists the actions still allowed in the current state, which a handheld app can turn into buttons.

Other cases follow the same logic. Stock is checked for every line before any reservation is written, and the error names the SKU, requested and available quantities. A stale If-Match header gets 412, while an exact retry of a shipment returns 200 without writing anything. A missing quantity is refused with 400 by using int? with [Required], and malformed JSON, which surfaced as a 500 in Development, is fixed through the StatusCodeSelector of UseExceptionHandler. The author also recommends running at least one integration test in the Development environment.

Real-world use

• A warehouse order API serving handheld scanners that run pick, pack and ship steps in sequence.
• A multi-channel commerce backend where concurrent orders compete for the same limited stock.
• Workflow endpoints behind flaky mobile networks, where clients retry requests and must not create duplicate changes.

Why it matters

Choosing the right status code tells the client what to do next: reload on 412, show a business conflict on 409, and treat a repeated 200 as success. Following these rules keeps workflow APIs from returning confusing 500 errors on the warehouse floor.

Related stories

• Sending leads to Odoo without losing one: a transactional outbox in ASP.NET CoreDVDEV Community: #aspnetcore2 d ago
• Vertical Slice vs Clean Architecture in .NET 10: the hybrid layoutCWMukesh Murugan (codewithmukesh)4 d ago
• Designing out double charges and overselling in an ASP.NET Core POSDVDEV Community: #aspnetcore6 d ago