=doc add section on Error vs. Failure for streams

… and some more clarifications after review.