doc: improve http.request documentation

This pull request adds some more specific documentation about how http.request works, which is very useful for someone who wants to know how to handle error conditions correctly.

I kind of don't think this will be accepted exactly as phrased, but this is a starting point.

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

n/a