REST API Design Best Practices for Validation and Error Handling

Overview

A REST API is easy to build when everything goes as expected. A client sends a request, the backend processes it, and the server returns a response.

The real challenge begins when things go wrong.

What happens when a client sends invalid data? What if the requested resource doesn’t exist? What if the same resource already exists? How should the API communicate an unexpected server failure?

A good REST API is not just about returning the right data. It should also make failures clear, consistent, and predictable.

This article examines practical principles for designing REST APIs that are easier to consume, test, and maintain.

REST APIs

1. Validate Requests at the Backend

Consider a product creation request:

{

“name”: “Laptop”,

“price”: -50000,

“stockQuantity”: -10

}

The JSON is valid, but the values are not.

It is common to perform validation on the frontend, but that should never be the only layer of validation. APIs can be called by mobile applications, other services, Postman, or completely different clients.

The backend should always treat incoming data as untrusted.

Spring Boot makes basic validation simple with Bean Validation:

Using @Valid in the controller allows invalid requests to be rejected before they reach the business logic.

The idea is simple:

Validate data as early as possible.

This prevents invalid information from reaching the service or database layer unnecessarily.

2. HTTP Status Codes Are Part of the API Contract

An API should clearly communicate the result of a request.

Consider:

GET /api/products/101

If product 101 exists, returning 200 OK makes sense.

But what if it doesn’t?

Returning:

200 OK

null

forces the client to guess what happened.

A better response would be:

404 Not Found

with a meaningful error body:

HTTP already provides status codes that describe common outcomes.

For example:

• 200 OK — Request completed successfully.
• 201 Created — A new resource was created.
• 400 Bad Request — The request contains invalid data.
• 404 Not Found — The requested resource doesn’t exist.
• 409 Conflict — The request conflicts with the current state of the application.
• 500 Internal Server Error — An unexpected server-side failure occurred.

Using these codes correctly makes the API easier to understand.

One important point is to avoid using 500 as a generic error response. A validation failure is different from an unexpected database or application failure.

3. Don’t Put All Error Handling Inside Controllers

As an application grows, controllers can quickly become filled with error-handling logic.

For example:

Doing this separately for products, customers, orders, and other resources leads to duplicated code.

It can also result in different controllers handling similar errors in different ways.

Spring provides @RestControllerAdvice to centralize exception handling.

The flow becomes:

Request

↓

Controller

↓

Service

↓

Exception

↓

Global Exception Handler

↓

HTTP Response

For example:

Now the controller can focus on handling the request, while the global exception handler is responsible for converting known exceptions into appropriate API responses.

This keeps error-handling logic centralized and easier to maintain.

4. Keep Error Responses Consistent

Status codes tell us what happened, but the response body should also follow a predictable structure.

Imagine one endpoint returns:

All three may represent similar failures, but their structures differ.

This makes API consumption unnecessarily complicated.

A consistent structure is easier to work with:

{

“code”: “PRODUCT_NOT_FOUND”,

“message”: “Product not found with id: 101”

}

The exact structure depends on the application. There is no single format that every API must follow.

What matters is consistency.

If frontend applications, mobile clients, or other backend services consume the API, they should be able to understand errors without having to implement different logic for every endpoint.

5. Keep Controllers Focused

A common mistake in backend applications is putting too much logic inside controllers.

A controller should primarily deal with HTTP concerns:

Request

↓

Controller

↓

Service

↓

Repository

↓

Database

The controller receives the request and passes the relevant information to the service.

The service handles business logic.

The repository handles data access.

Validation handles invalid input.

Exception handling deals with failures.

Keeping these responsibilities separate makes the code easier to understand and maintain.

For example, a controller shouldn’t need to know how a product is stored in the database or how a particular business rule is calculated.

Its main responsibility is to translate between the HTTP and application layers.

6. API Design Also Affects Testing

A predictable API is much easier to test.

Consider a product API.

A successful creation should result in:

Valid request

↓

201 Created

An invalid request:

Invalid price

↓

400 Bad Request

A missing resource:

Product doesn’t exist

↓

404 Not Found

A duplicate resource:

Product already exists

↓

409 Conflict

An unexpected failure:

Server failure

↓

500 Internal Server Error

Tests can verify not only that the API returns a response, but that it returns the correct response for a particular situation.

This becomes increasingly important as an application grows and multiple developers or teams start consuming the same APIs.

7. Common Mistakes to Avoid

A few mistakes appear frequently when designing REST APIs.

Returning 200 OK for every situation

A successful request and a failed request should not look identical.

Relying only on frontend validation

The backend must validate requests independently.

Returning raw exceptions

Internal exception messages can expose implementation details that clients don’t need to know.

Duplicating exception handling

If every controller handles the same exceptions differently, maintaining the API becomes harder.

Inconsistent error structures

Consumers should not need to learn a different error format for every endpoint.

Putting business logic in controllers

Controllers become difficult to maintain when they are responsible for validation, business rules, database operations, and error handling all at once.

Conclusion

A REST API is more than a collection of endpoints that return data.

A production API also needs to define what happens when requests are invalid, resources don’t exist, operations conflict, or unexpected failures occur.

Backend validation protects the application from invalid input.

HTTP status codes communicate the outcome of a request.

Centralized exception handling keeps error management maintainable.

Consistent error responses make APIs easier to consume and test.

These concepts are not particularly complicated. The important part is applying them consistently.

Good API design ultimately comes down to one simple principle:

Don’t make the consumer guess what happened.

Whether a request succeeds or fails, the API should communicate the result clearly, consistently, and predictably.

Drop a query if you have any questions regarding REST API, and we will get back to you quickly.