CURLOPT_FAILONERROR forces connection to be closed

[bemoody]

If CURLOPT_FAILONERROR is used, and the server returns an error,
the connection will be closed immediately, regardless of the HTTP
version and keep-alive headers.

I guess that the reason this is done is so that libcurl doesn't
have to wait to receive the body of the error page. However,
error pages tend to be small, and it seems likely to me that in
many cases (if the application is making a large number of
requests, and especially when using HTTPS), it's more efficient
just to download the error page and discard it, rather than
having to open a new connection to the server. Moreover, in the
case of HEAD requests, there is no reason to close the connection
at all.

Of course, it is possible to work around this at the application
level - instead of setting CURLOPT_FAILONERROR, check the
CURLINFO_RESPONSE_CODE, and if it's >= 400, ignore the body of
the response. However, that has its own problems: aside from
being annoying to implement, it relies on the assumption that all
future protocols supported by libcurl will use HTTP/FTP-like
response codes.

[bagder]

This behavior should be documented to not be a surprise to users. Note how the documentation already limits this functionality to HTTP.

It is closed for HEAD as well as it allows for libcurl to return without even reading the full set of headers.

[bagder]

This behavior is now documented as of commit 37402b5