Framework Design Guidelines: The right number of exceptions

A reader asks me about a salutation where they are catching a SoapException and wrapping it with their own API specific exception type. I think this is a fairly common scenario so I wanted to start a dialog about it here.

Part of this is covered in chapter 7 of Framework Design Guidelines.

First, it is goodness to wrap the SoapException with your own custom exception type. Essentially you are abstracting away some implementation detail of your framework. Today you may use ASMX, tomorrow you may use Indigo.. I mean WCF... to access it, you don’t want the public contract of your framework to change as those implementation details change.

In this particular case the SoapException could indicate 100+ reasons why the call failed, is it a good idea to wrap all 100+ reasons into one exception or should we create 100+ exceptions to expose that level of detail to the API caller? Neither of these is a good idea. Using just one exception is likely to mask issues together that should be called out and creating over 100 exception types is way overkill. So forget the implementation detail of how the errors get to you (the SoapException) and think only about how consumers of your framework are going to want to consume those errors. For example there are probably some logical groupings of errors that the user will want to handle in a very similar way. For example any kind of error on the server side may want to be logged for an admin to look at. Group each of these in their own exception type (maybe subclass of common base) possibly with some programmatic way to find the specific issue if needed. You should also think if there are errors you can handle in your own framework, for example your framework might decide to retry twice on a “server busy” error before it throws it back to the caller. All such cases should be well documented of course.

Have other folks run into this scenario? What did you do?