Validation Errors

A useful validation response should help the caller make a successful next attempt. Suppose a customer submits an order draft containing three books, and two quantities are invalid. If the API responds only with “Invalid request,” the customer cannot tell which entries need attention. Reporting one issue at a time is also frustrating: each correction may reveal another failure and require another round trip.

Validation errors should identify what the caller can correct, where the problem occurred, and which rule the input violated.

This chapter uses a fictional bookstore's JSON API over HTTPS to explain validation stages, precise error locations, related-field rules, and predictable failure behavior. The examples assume a Problem Details error contract with an application-defined errors array.