Hey everyone! I'm working on a personal project where I'm trying to create a library that documents HTTP exceptions in FastAPI for use in Swagger and Redoc. My approach involves defining classes for each possible exception and using a helper function to generate an OpenAPI dictionary. This way, developers using my API can easily understand what errors they might encounter. I'm curious if this is a common approach or if there's a better way to handle documentation for HTTP exceptions. I'd love to hear about your experiences and suggestions! Here's a quick example of how I'm going about it:
3 Answers
I'd advise against creating your own classes for these exceptions since they already exist. Reinventing the wheel can lead to issues with compatibility. Rather than documenting every individual error, just relying on standard HTTP status codes is usually enough since they're universal. If you define too many of your own, it might drift more into RPC territory rather than staying RESTful.
Exactly! Focusing on specific use cases for errors can really help clarify things, rather than reiterating common codes.
Personally, I avoid making custom exceptions unless absolutely necessary. I prefer to utilize the standard library exceptions and the ones that FastAPI provides. The only times I'd define my own is when I need to track a specific type of error that could get lost among others. For example, if I have a situation where a ValueError might not be sufficient, I might create a specialized one, but that doesn't happen often.
I think it's generally frowned upon to redefine HTTP errors when the standard ones work just fine. Plus, if you're using a 404 when the API key is missing, that could confuse users since it should really be a 403. You might want to reconsider the status codes you're using, as changing them can lead to inconsistencies with the HTTP specification.
Honestly, missing API keys usually warrant a 401 error. A 403 should be reserved for cases where the key is valid but lacks permissions. It's important to keep the semantics clear!
You mentioned using 404 in your documentation—it’s good to know how to classify errors, but it seems like that could lead to confusion if grouping errors isn’t done correctly.
I get what you're saying. It's more important to identify domain-specific errors for clients rather than explain what an error code generally means. But I wonder if it's ever necessary to associate a single exception code with multiple potential errors?