Possible NSError from a message documented anywhere?

Question

Are all NSErrors that may result from a message ever documented anywhere in the cocoa or iOS frameworks?

Yes the types of NSErrors are divided into different domains, still I'm looking at say NSURLSession and it seems like message such as (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData completionHandler:(void (^)(NSURL *location, NSURLResponse *response, NSError *error))completionHandler does not specify what possible NSError could be thrown out. And in the Apple's own Error handling programming guide, it uses NSDocument as example, but in the reference docs it doesn't say what errors can be thrown out either.

Am I missing something? How would a programmer know in advance what type of possible errors that could happen? Or do programs typically just do a catch all and throw them back to the user via alerts?

(I program for iOS)

Answer 1

Are all NSErrors that may result from a message ever documented anywhere in the cocoa or iOS frameworks?

The existence of NSOSStatusErrorDomain means the answer is no, because there are literally thousands of OSStatus error codes and only some fraction of them are documented.

Most, if not all, errors in other Apple-supplied domains are documented, though. You should be able to simply get an error's localized description, localized failure reason, or localized recovery suggestion to get a description of the error that's (theoretically) fit to show to the user.

… I'm looking at say NSURLSession and it seems like [it] does not specify what possible NSError could be thrown out. And in the Apple's own Error handling programming guide, it uses NSDocument as example, but in the reference docs it doesn't say what errors can be thrown out either.

The set of possible errors is very seldom constrained and very often a moving target.

The NSDocument example is a good example of the first part: you can return literally any error from the read and write methods. Anything that goes wrong when trying to read (e.g.: corrupt/wrong format, nonsense data) or write (e.g.: can't create file; insufficient space left in storage), you report as an error. You can even make up your own errors and those are totally valid to return from there.

Even in the case of NSURLSessionDownloadTask, there may be some finite set of imaginable things that could go wrong, but that just means you'll be expecting the same set of failure cases that Apple's engineers are. When (not if) something happens that they weren't expecting, you won't be, either.

“Apple never said this will happen!” is a poor excuse for your application not handling errors properly.

And “never” might not be true: As I mentioned, the set of possible errors may be a moving target. That means that Apple may expand that set later, either because they forgot one (it happens) or because they truly added other possible errors (new codes or just newly-handled cases) later.

If you expect Apple to perfectly completely document every method's set of present and future possible errors, you will be disappointed. Expect imperfection and plan around it.

If you receive an error, you need to be able to handle ANY error. Recover from anything you can, make sure all the foreseeable unrecoverable cases have reasonable error messages (if they don't already), and handle anything else by stuffing its localized description/failure reason/recovery suggestion in an alert.