Add Error Handling to Flask APIs

You've built a Flask API that returns JSON when everything goes right. But what happens when a user requests a resource that doesn't exist, sends malformed data, or your database connection drops? By default, Flask returns a plain-text HTML error page — useless for API clients expecting structured JSON. Your API's reliability is judged by how gracefully it fails. In this lesson, you'll learn to add error handling to Flask APIs, turning ugly tracebacks into clean, consistent JSON errors, so your clients can respond intelligently and you can debug production issues with confidence.

The problem this lesson solves

Unhandled errors in a Flask API create several problems:

• Poor client experience — Clients receive HTML error pages with stack traces, which are unparseable and can leak sensitive information.
• Inconsistent API contract — Each error returns a different format (or no format at all), forcing clients to write fragile parsing logic.
• Wasted debugging time — Without structured logs and error context, you must guess what went wrong in production.
• Unhandled exceptions — Default Flask behavior catches nothing beyond HTTP errors, so unexpected bugs result in a 500 with no details.

Consider this simple API without error handling:

from flask import Flask, jsonify

app = Flask(__name__)

users = {1: "Alice", 2: "Bob"}

@app.route("/api/users/<int:user_id>")
def get_user(user_id):
    return jsonify({"id": user_id, "name": users[user_id]})

if __name__ == "__main__":
    app.run()

Requesting /api/users/3 raises a KeyError, and Flask returns a 500 Internal Server Error with an HTML page. That's a disaster for a mobile app expecting JSON.

Core concept / mental model

Think of your Flask app as a gatekeeper that inspects every request and controls every response. Error handling is the rulebook for what happens when something goes wrong — whether the client made a mistake (4xx) or the server failed (5xx).

Flask provides two complementary mechanisms:

1. HTTP error handlers — Register functions that run when an HTTP status code (like 404 or 500) is triggered, either explicitly via abort() or automatically by Flask.
2. Exception handlers — Catch exceptions raised anywhere in your view code, convert them into JSON responses with the right status code.

You register both with the @app.errorhandler decorator. The handler receives the error object and must return a response — typically (json_response, status_code).

The mental model: every request flows through a pipeline. If any step raises an error, Flask consults your error handler registry. If a handler exists for that error type, it returns a controlled JSON response; otherwise, Flask falls back to its default HTML error page. By defining handlers for 404, 405, 500, and custom exceptions, you cover the vast majority of failure cases.

How it works step by step

1. Identify the error types you need to handle — Client errors (400 Bad Request, 404 Not Found, 422 Unprocessable Entity) and server errors (500 Internal Server Error).
2. Create a consistent JSON error format — Decide on a structure, e.g., {"error": true, "message": "...", "details": {}}. Consistency is key so clients can parse it reliably.
3. Register error handlers — Use @app.errorhandler(404) for HTTP errors, @app.errorhandler(Exception) for unhandled exceptions, and @app.errorhandler(CustomError) for your own exception classes.
4. Raise errors in views — Use abort(404) or raise your custom exception when something goes wrong.
5. Log errors effectively — In production, log full tracebacks to a file or external service, but return only a generic message to the client.
6. Test your handlers — Simulate errors by running the app and hitting bad endpoints.

The cause-and-effect chain is simple: an error is raised → Flask catches it → your handler runs → a JSON response is returned → the client handles it gracefully.

Hands-on walkthrough

Let's extend the example from the problem section with proper error handling.

1. Basic HTTP error handlers

from flask import Flask, jsonify, abort

app = Flask(__name__)

users = {1: "Alice", 2: "Bob"}

@app.route("/api/users/<int:user_id>")
def get_user(user_id):
    user = users.get(user_id)
    if user is None:
        abort(404, description=f"User {user_id} not found")
    return jsonify({"id": user_id, "name": user})

@app.errorhandler(404)
def not_found(error):
    response = jsonify({
        "error": True,
        "message": error.description or "Resource not found",
        "status": 404
    })
    response.status_code = 404
    return response

@app.errorhandler(400)
def bad_request(error):
    response = jsonify({
        "error": True,
        "message": error.description or "Bad request",
        "status": 400
    })
    response.status_code = 400
    return response

if __name__ == "__main__":
    app.run(debug=True)

Expected output for GET /api/users/3:

{
  "error": true,
  "message": "User 3 not found",
  "status": 404
}

2. Handling validation errors with a custom exception

For APIs with request data, it's common to validate payloads. Instead of scattering abort(400) everywhere, define a custom exception:

class ValidationError(Exception):
    def __init__(self, message, errors=None):
        super().__init__(message)
        self.message = message
        self.errors = errors

@app.errorhandler(ValidationError)
def handle_validation_error(error):
    response = jsonify({
        "error": True,
        "message": error.message,
        "details": error.errors,
        "status": 422
    })
    response.status_code = 422
    return response

@app.route("/api/users", methods=["POST"])
def create_user():
    data = request.get_json()
    if not data or "name" not in data:
        raise ValidationError("Missing required field: name", errors={"name": "This field is required"})
    # Create user...
    return jsonify({"id": 3, "name": data["name"]}), 201

Now, sending a POST without name returns a 422 with structured details, instead of a bare 400. Clients can highlight exactly which field failed.

3. Global exception handler for unexpected errors

Even with great validation, bugs happen. Add a catch-all handler for any unhandled exception:

import logging
from flask import Flask, jsonify

app = Flask(__name__)

# Configure logging to console/file
logging.basicConfig(filename='app.log', level=logging.ERROR)

@app.errorhandler(Exception)
def handle_unexpected_error(error):
    # Log the full traceback for debugging
    app.logger.error('Unhandled exception', exc_info=error)
    response = jsonify({
        "error": True,
        "message": "Internal server error",
        "status": 500
    })
    response.status_code = 500
    return response

Pro tip: In debug mode, Flask ignores custom handlers for unhandled exceptions to show the debugger. Test your 500 handler with debug=False (or in a production-like environment).

4. Complete example combining everything

from flask import Flask, jsonify, request, abort
import logging

app = Flask(__name__)
logging.basicConfig(filename='app.log', level=logging.ERROR)

class ValidationError(Exception):
    pass

users = {1: "Alice", 2: "Bob"}

@app.errorhandler(404)
def not_found(error):
    return jsonify({"error": True, "message": "Resource not found", "status": 404}), 404

@app.errorhandler(400)
def bad_request(error):
    return jsonify({"error": True, "message": error.description or "Bad request", "status": 400}), 400

@app.errorhandler(ValidationError)
def validation_error(error):
    return jsonify({"error": True, "message": str(error), "status": 422}), 422

@app.errorhandler(Exception)
def unhandled_exception(error):
    app.logger.error('Unhandled exception', exc_info=error)
    return jsonify({"error": True, "message": "Internal server error", "status": 500}), 500

@app.route("/api/users/<int:user_id>")
def get_user(user_id):
    if user_id not in users:
        abort(404, description=f"User {user_id} not found")
    return jsonify({"id": user_id, "name": users[user_id]})

@app.route("/api/users", methods=["POST"])
def create_user():
    data = request.get_json(silent=True)
    if not data or "name" not in data:
        raise ValidationError("Missing required field: name")
    return jsonify({"id": 3, "name": data["name"]}), 201

if __name__ == "__main__":
    app.run()

Test with curl:

curl http://localhost:5000/api/users/3
# Returns 404 JSON
curl -X POST http://localhost:5000/api/users -H "Content-Type: application/json" -d '{}'
# Returns 422 JSON

Compare options / when to choose what

When to choose what: Use built-in HTTP handlers for 404, 405, and 400. Use custom exceptions for validation or business logic errors. Always include a global exception handler as a safety net, and log everything so you can debug.

Troubleshooting & edge cases

• Handler not being called for abort(404) — Ensure you registered the handler after your app instance is created, not inside a function that runs at import time. Also check that you're not using debug=True in a way that overrides error pages.
• abort(404, description=...) shows HTML — If you haven't registered a 404 handler, Flask returns HTML. Make sure your handler returns a JSON response, not just a string.
• Getting 500 instead of 422 for validation errors — If you raise a custom exception but forget to include @app.errorhandler(ValidationError), Flask treats it as an unhandled exception. Always register your custom exceptions.
• Global exception handler swallowing all errors — If you catch Exception but don't log, you'll never know what failed. Always use exc_info=True in your logging call.
• Error handler for 405 Method Not Allowed — You need a separate handler for 405, because Flask doesn't auto-route to your 400 handler for wrong methods.
• Returning strings vs tuples — When your handler returns a bare string, Flask sends it as HTML. Always return jsonify(...) or a tuple (json_response, status_code).

What you learned & what's next

You've learned the core idea behind adding error handling to Flask APIs: converting failures into predictable JSON responses while logging for your own debugging. You can now handle standard HTTP errors, create custom exceptions for domain-specific problems, and guard against unexpected bugs with a global handler. You know how to test your handlers and have practical troubleshooting tips for common pitfalls.

Next in your Python web development track: Now that your API can fail gracefully, you'll move on to structuring larger applications with Blueprints and Flask extensions to keep your code organized as your API grows.