FastAPI Error Handling and Validation Responses

1. Automatic Validation Errors: The 422 Unprocessable Entity

One of FastAPI's most powerful features is its tight integration with Pydantic. When you define a type hint for a path parameter, query parameter, or request body, FastAPI uses it as a validation rule. If an incoming request violates this rule, FastAPI automatically intercepts it and returns a specific HTTP error.

Let's start by reading a concise explanation of this automatic process.

As the article mentions, you get a 422 Unprocessable Entity status code. This code signifies that the server understands the request's content type and the syntax of the request entity is correct, but it was unable to process the contained instructions. In simpler terms: "I know you sent me JSON, but the data inside it is wrong."

2. Interpreting the Error Response

FastAPI doesn't just say "something is wrong"; it gives you a detailed JSON response explaining exactly what is wrong. This is incredibly helpful for debugging and for client-side applications that need to display user-friendly error messages.

The error response has a standard structure. Let's examine it.

The three key fields in each error object are:

• loc: A list indicating the location of the error in the incoming data. For a request body, it will be ["body", "field_name"]. For a path parameter, it would be ["path", "param_name"].
• msg: A human-readable message explaining the error.
• type: A machine-readable string indicating the type of error (e.g., value_error.missing, type_error.float).

Here is a visual example of such an error.

Let's see this in action. The following video demonstrates how these errors appear in the interactive documentation when you test an endpoint with invalid data.

This automatic validation isn't limited to request bodies. It works for path and query parameters too, based on their Python type hints.

3. Raising Your Own Errors with HTTPException

Automatic validation is for data that is structurally or typographically incorrect. But what about errors related to your application's business logic?

• A client requests a resource with an ID that doesn't exist in your database (/items/999).
• A user tries to perform an action for which they don't have permission.
• An ML model receives validly structured input that is nonsensical in the problem context (e.g., a house area of -100 sqft).

In these cases, the data is "valid" according to Pydantic, but "invalid" according to your rules. For this, you need to manually raise an exception. FastAPI provides HTTPException for this purpose.

The key is to use the correct HTTP status code to communicate the nature of the error. Common client-side error codes include:

• 400 Bad Request: A generic error for when the client sends a request that the server cannot process, often due to a business logic failure.
• 404 Not Found: The requested resource does not exist.
• 403 Forbidden: The client is authenticated, but not authorized to perform the action.
• 409 Conflict: The request could not be completed due to a conflict with the current state of the resource (e.g., trying to create a user with an email that already exists).

Let's watch a practical example of refactoring code to use HTTPException for a "not found" scenario.

4. Hands-On Practice: Adding Business Logic Validation

Let's apply this to our ML prediction endpoint. While Pydantic ensures we get numbers for area_sqft and num_bedrooms, it doesn't know that a value of 0 for num_bedrooms might be illogical for a house price prediction. We'll add a check for this using HTTPException.

Task:

In your main.py file:

1. Make sure you have HTTPException imported from FastAPI: from fastapi import FastAPI, HTTPException.
2. In your predict_house_price endpoint, add a business logic check right after the function definition. If house_data.num_bedrooms is less than 1, it's an invalid request.
3. If the condition is true, raise an HTTPException with a status_code of 400 (Bad Request) and a helpful detail message, like "Number of bedrooms must be a positive number."
4. Run your app and test the endpoint in the Swagger UI:
   • First, send a request with num_bedrooms: 0. You should see your custom 400 Bad Request error.
   • Then, send a request with area_sqft: "invalid-string". You should see FastAPI's automatic 422 Unprocessable Entity error. This will help solidify the difference between the two types of errors.

# In main.py
# You should already have your Pydantic models and the app instance defined.
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI()

class HousePredictionInput(BaseModel):
  area_sqft: float = Field(..., gt=0, description="Area of the house in square feet")
  num_bedrooms: int = Field(..., gt=0, description="Number of bedrooms")
  has_garage: bool

class HousePredictionOutput(BaseModel):
  predicted_price: float

@app.post("/predict/house-price", response_model=HousePredictionOutput)
async def predict_house_price(house_data: HousePredictionInput):



  # Our new business logic check
  if house_data.num_bedrooms < 1:
      raise HTTPException(status_code=400, detail="Number of bedrooms must be a positive number.")




  # Dummy prediction logic (same as before)
  predicted_price = 150_000 + (house_data.area_sqft * 150) + (house_data.num_bedrooms * 20_000)
  if house_data.has_garage:
      predicted_price += 25_000
  
  return {"predicted_price": predicted_price}

Conclusion

Excellent work! You now have a solid understanding of FastAPI's two-tiered error handling system.

Key Takeaways:

• Automatic Validation Errors: FastAPI automatically returns a 422 Unprocessable Entity error when incoming data fails Pydantic validation. The JSON response detail field tells you the precise loc (location), msg (message), and type of each error.
• Business Logic Errors: For custom validation rules (e.g., checking if a resource exists, validating logical constraints), you should manually raise HTTPException.
• Status Codes Matter: Using the correct HTTP status code (422, 404, 400, etc.) is essential for building a predictable and reliable API that clients can easily integrate with.

In our next lesson, we will continue building on our knowledge of Pydantic by learning how to combine path, query, and body parameters in a single endpoint, seeing how FastAPI seamlessly handles validation for all of them at once.