Adds more API error return code requirements

Adds information about the reason that error codes
can be returned by a method. This will help ensure that
people consider more of the semantics (especially the error paths)
of new API methods.

Change-Id: Ia2ff1fd2e689f5c0fad0a84e807de07d150ae9ee