Undocumented jQuery.ajax() differences between .fail() and error callback.

On http://api.jquery.com/jquery.ajax/#jqXHR jqXHR.fail() it's described with these word:

jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});

An alternative construct to the error callback option, the .fail() method replaces the deprecated .error() method. Refer to deferred.fail() for implementation details.

An alternative construct suggests that using any of these methods will result in the same behavior. In fact they differ quite significantly, because error is not called when beforeSend returns false, while .fail() is called in that case, additionally with completely undocumented canceled status. It looks like all that stuff came with http://bugs.jquery.com/ticket/10944 and the changes it brought have not been documented at all.

Start with the jqXHR.fail() section on http://api.jquery.com/jquery.ajax/#jqXHR and compare its description with the error callback behavior described in the issue. Review the behavior associated with bugs.jquery.com/ticket/10944, then document the beforeSend cancellation difference and the canceled status so the two APIs are no longer presented as equivalent.