Error Handling

Understand how errors are handled and returned in the Cinefinder API

Overview

The Cinefinder API implements a centralized error handling system using Spring’s @RestControllerAdvice. All exceptions are caught and transformed into consistent error responses with detailed information.

Error Response Format

All errors follow a consistent JSON structure defined in ErrorResponse:

{
  "type": "error",
  "code": "404",
  "details": "No se encontró la película con el título: Inception",
  "location": "uri=/peliculas/Inception",
  "moreInfo": "No se encontró en la ruta: /peliculas/Inception",
  "timestamp": "2026-03-04T10:30:45.123"
}

Response Fields

type · string

Always returns "error" to indicate an error response

code · string

HTTP status code as a string (e.g., “400”, “404”, “500”)

details · string

Detailed error message describing what went wrong

location · string

The URI or request path where the error occurred

moreInfo · string

Additional context or helpful information about the error

timestamp · string

ISO 8601 timestamp when the error occurred

Exception Hierarchy

Base Exceptions

The API defines custom exception classes that extend RuntimeException:

RecursoNoEncontradoException

HTTP Status: 404 NOT FOUND

Thrown when a requested resource cannot be found.

throw new RecursoNoEncontradoException("No se encontró la película con id: " + id);

Example Response:

{
  "type": "error",
  "code": "404",
  "details": "No se encontró la película con id: 123",
  "location": "uri=/peliculas/123",
  "moreInfo": "No se encontró en la ruta: /peliculas/123",
  "timestamp": "2026-03-04T10:30:45.123"
}

ValidacionException

HTTP Status: 400 BAD REQUEST (when handled)

Thrown when validation logic fails.

throw new ValidacionException("Los datos proporcionados no son válidos");

Domain-Specific Exceptions

The API implements specific exceptions for each domain entity:

Película Exceptions

PeliculaTituloYaExistenteException

Status: 400 BAD REQUEST

Thrown when attempting to create a película with a title that already exists.

throw new PeliculaTituloYaExistenteException("Inception");

Response:

{
  "type": "error",
  "code": "400",
  "details": "Ya existe una película con el titulo de: Inception, por favor, intente con otro distinto",
  "location": "uri=/peliculas",
  "moreInfo": "No se pudo ingresar una pelicula categoria error en: /peliculas",
  "timestamp": "2026-03-04T10:30:45.123"
}

PeliculaNoActualizadaException

Status: 400 BAD REQUEST

Thrown when a película update operation fails.

Response:

{
  "type": "error",
  "code": "400",
  "details": "Error message",
  "location": "uri=/peliculas/123",
  "moreInfo": "No se pudo actualizar la pelicula error en: /peliculas/123",
  "timestamp": "2026-03-04T10:30:45.123"
}

PeliculaNoEliminadaException

Status: 400 BAD REQUEST

Thrown when a película deletion operation fails.

Response:

{
  "type": "error",
  "code": "400",
  "details": "Error message",
  "location": "uri=/peliculas/123",
  "moreInfo": "No se pudo eliminar la categoria error en: /peliculas/123",
  "timestamp": "2026-03-04T10:30:45.123"
}

Categoría Exceptions

CategoriaNombreYaExistenteException

Status: 400 BAD REQUEST

Thrown when attempting to create a category with a name that already exists.

throw new CategoriaNombreYaExistenteException("Drama");

Response:

{
  "type": "error",
  "code": "400",
  "details": "Ya existe una categoría con el nombre: Drama, por favor, intente con otro distinto",
  "location": "uri=/categorias",
  "moreInfo": "No se pudo ingresar una nueva categoria error en: /categorias",
  "timestamp": "2026-03-04T10:30:45.123"
}

CategoriaNoActualizadaException

Status: 400 BAD REQUEST

Thrown when a category update operation fails.

CategoriaNoEliminadaException

Status: 400 BAD REQUEST

Thrown when a category deletion operation fails.

Artista Exceptions

ArtistaYaRegistradoException

Status: 400 BAD REQUEST

Thrown when attempting to register an artist that already exists.

Response:

{
  "type": "error",
  "code": "400",
  "details": "Error message",
  "location": "uri=/artistas",
  "moreInfo": "No se pudo ingresar una pelicula categoria error en: /artistas",
  "timestamp": "2026-03-04T10:30:45.123"
}

ArtistaNoActualizadoException

Status: 400 BAD REQUEST

Thrown when an artist update operation fails.

ArtistaNoEliminadoException

Status: 400 BAD REQUEST

Thrown when an artist deletion operation fails.

Global Exception Handler

The GlobalExceptionHandler class (located at src/main/java/com/trainee/Cinefinder/exceptions/GlobalExceptionHandler.java) intercepts all exceptions using @RestControllerAdvice.

Exception Handler Methods

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(RecursoNoEncontradoException.class)
    public ResponseEntity<ErrorResponse> handlerRecursoNoEncontrado(
        RecursoNoEncontradoException ex, 
        WebRequest request
    ) {
        ErrorResponse error = ErrorResponse.builder()
            .code(String.valueOf(HttpStatus.NOT_FOUND))
            .details(ex.getMessage())
            .location(request.getDescription(true))
            .moreInfo("No se encontró en la ruta: " + 
                request.getDescription(false).replace("uri=", ""))
            .timestamp(LocalDateTime.now())
            .build();
        
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }
    
    // ... other specific handlers
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneralException(
        Exception ex, 
        WebRequest request
    ) {
        ErrorResponse error = ErrorResponse.builder()
            .code("500")
            .details(ex.getMessage())
            .location(request.getDescription(false))
            .moreInfo("Ocurrió un error inesperado")
            .timestamp(LocalDateTime.now())
            .build();
        
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

HTTP Status Codes

The API uses standard HTTP status codes:

200 OK · success

Request succeeded

201 CREATED · success

Resource was successfully created

400 BAD REQUEST · error

Invalid request data, duplicate resource, or business logic error

404 NOT FOUND · error

Requested resource does not exist

500 INTERNAL SERVER ERROR · error

Unexpected server error occurred

Error Handling Best Practices

Always check the HTTP status code before parsing the response body. A 2xx status indicates success, while 4xx and 5xx indicate errors.

Example: Handling Errors in Client Code

try {
  const response = await fetch('http://localhost:8080/peliculas', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      titulo: 'Inception',
      sipnosis: 'A thief who steals corporate secrets...',
      duracion: 148,
      categoria_id: 1
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('Error:', error.details);
    console.error('More info:', error.moreInfo);
    // Handle specific error codes
    if (error.code === '400') {
      // Handle bad request (duplicate, validation, etc.)
    }
  } else {
    const data = await response.json();
    // Handle success
  }
} catch (error) {
  console.error('Network error:', error);
}

Common Error Scenarios

Duplicate Resource

Request:

curl -X POST "http://localhost:8080/peliculas" \
  -H "Content-Type: application/json" \
  -d '{"titulo":"Inception","sipnosis":"...","duracion":148,"categoria_id":1}'

Response (400):

{
  "type": "error",
  "code": "400",
  "details": "Ya existe una película con el titulo de: Inception, por favor, intente con otro distinto",
  "location": "uri=/peliculas",
  "moreInfo": "No se pudo ingresar una pelicula categoria error en: /peliculas",
  "timestamp": "2026-03-04T10:30:45.123"
}

Resource Not Found

Request:

curl -X GET "http://localhost:8080/peliculas/NonExistentMovie"

Response (404):

{
  "type": "error",
  "code": "404",
  "details": "No se encontró la película",
  "location": "uri=/peliculas/NonExistentMovie",
  "moreInfo": "No se encontró en la ruta: /peliculas/NonExistentMovie",
  "timestamp": "2026-03-04T10:30:45.123"
}

Internal Server Error

Response (500):

{
  "type": "error",
  "code": "500",
  "details": "Error message details",
  "location": "uri=/endpoint",
  "moreInfo": "Ocurrió un error inesperado",
  "timestamp": "2026-03-04T10:30:45.123"
}

Next Steps

Validation

Learn about request validation patterns

Authentication

Understand authentication (future implementation)