What is the difference between .catch and .fail in jQuery?

Question

The short doc for .fail says:

Add handlers to be called when the Deferred object is rejected.

and the short doc for .catch is exactly the same:

Add handlers to be called when the Deferred object is rejected.

Source: http://api.jquery.com/category/deferred-object/

The arguments accepted by the two methods seem to be different, and the doc of .catch states that .catch is an alias of .then(null, fn)

Are there cases where I should use .fail and others where I should use .catch?

Or ... if I only have one function ... are following commands interchangeable and they only exist for compatibility/historical reasons?

a) .fail(fn)  b) .catch(fn)  c) .then(null, fn) 

I created a jsFiddle:

https://jsfiddle.net/sq3mh9j5/

If there is a difference, could you please provide some examples since I am new to jquery and not yet familiar with all promise terms.

Why does the doc of .catch does not reference the doc of .fail and clarify the difference/similarity?

Edit I found some notes in the 3.0 release notes that the behavior of .then changed. https://blog.jquery.com/2015/07/13/jquery-3-0-and-jquery-compat-3-0-alpha-versions-released/ Nevertheless I am still unsure when to use .fail and when to use .catch.

Answer 1

catch and fail are slightly different, in that catch will return a new (resolved) promise, whereas fail will return the original promise.

// This will only output "fail" $.Deferred()   .reject(new Error("something went wrong"))   .fail(function() {     console.log("fail");   })   .then(function() {     console.log("then after fail");   }) 

// This will output "catch" and "then after catch" $.Deferred()   .reject(new Error("something went wrong"))   .catch(function() {     console.log("catch");   })   .then(function() {     console.log("then after catch");   }) 

Note that catch(fn) is an alias of then(null, fn).