Document the possible errors returned by drupal_http_request()

Here's a copy of my comment over at the docs page for drupal_http_request(). Basically what it boils down to is that the documentation could be improved to explain where the errors may be coming from, and perhaps list some of the most common ones (as listed below).

While debugging various unexpected error codes, I found out that $result->code can actually contain far more things than merely the HTTP response codes. The documentation does not make this very clear:

code: An integer containing the response status code, or the error code if an error occurred.

Here's a list of error codes you may encounter, with their meaning ($result->error), grouped by source:

• Error codes stemming from the function itself:
  • -1 (request timed out)
  • -1001 (unable to parse URL)
  • -1002 (missing schema)
  • -1003 (invalid schema [schema])
• HTTP response codes (if an error, it will be the name of the HTTP status message as returned by the web server):
  • 200
  • 404 (Not Found)
  • 500 (Internal Server Error)
  • etc...
• Error codes returned by stream_socket_client(), negated to prevent clashing with HTTP status codes. God knows if they may collide with the negative error codes the function itself can return, though. As per the docs, most of the time errors from this will be the error from the actual connect() system call. The actual numerical values of the errors are listed here. I've also seen error code 0 and I have no idea what that could mean:
  • -110 (Connection timed out)
  • -111 (Connection refused)
  • etc...
  • 0 (????)