How should I handle errors in an API?

Question

I am writing an API that wraps some core foundation web functionality that can return a number of possible error conditions. I am struggling with deciding the best way to handle error conditions that the API consumer should deal with (like network timeouts, receiving unexpected results, malformed XML, etc). I have come up with 3 different models, but am uncertain about which model to use:

Given an object with a method takeAction that does not return any value, should I handle an error in the method by:

1. write the method to be - (BOOL)takeAction:(NSError **)error so that the consumer knows the method succeeded or failed, and can inspect the error object to determine why,

2. write the method to be - (BOOL)takeAction so that, again, the consumer knows if the method succeeded or failed, and can then call - (NSError *)getLastError to determine why the method failed, or

3. write it as - (void)takeAction and post a notification so that the consumer can subscribe to the notification and pass the NSError object in the notification's userInfo dictionary?

Which is preferable?

Answer 1

I would go with approach number 1. This is what Apple commonly does in their APIs, such as saving files, etc. The benefits of this approach are being able to quickly see if it passed or failed (by returning a boolean), and immediately having access to the error. This is mostly the same as number 2, but you can now have more than one error object if you need it (instead of just the single "getLastError"). This will make things clearer when tracking down specific errors when there could be potentially multiple error-prone methods called in succession.