Angular HttpPromise: difference between `success`/`error` methods and `then`'s arguments

According to AngularJS doc, calls to $http return the following:

Returns a promise object with the standard then method and two http specific methods: success and error. The then method takes two arguments a success and an error callback which will be called with a response object. The success and error methods take a single argument - a function that will be called when the request succeeds or fails respectively. The arguments passed into these functions are destructured representation of the response object passed into the then method.

Aside from the fact that the response object is destructured in one case, I don't get the difference between

• the success/error callbacks passed to be passed as arguments of promise.then
• the callbacks passed as arguments for the promise.success/promise.error methods of the promise

Is there any? What's the point of these two different ways to pass seemingly identical callbacks?

There are some good answers here already. But it's worthwhile to drive home the difference in parallelism offered:

• success() returns the original promise
• then() returns a new promise

The difference is then() drives sequential operations, since each call returns a new promise.

$http.get(/*...*/).
  then(function seqFunc1(response){/*...*/}).
  then(function seqFunc2(response){/*...*/})

1. $http.get()
2. seqFunc1()
3. seqFunc2()

success() drives parallel operations, since handlers are chained on the same promise.

$http(/*...*/).
  success(function parFunc1(data){/*...*/}).
  success(function parFunc2(data){/*...*/})

1. $http.get()
2. parFunc1(), parFunc2() in parallel

NB This answer is factually incorrect; as pointed out by a comment below, success() does return the original promise. I'll not change; and leave it to OP to edit.

The major difference between the 2 is that .then() call returns a promise (resolved with a value returned from a callback) while .success() is more traditional way of registering callbacks and doesn't return a promise.

Promise-based callbacks (.then()) make it easy to chain promises (do a call, interpret results and then do another call, interpret results, do yet another call etc.).

The .success() method is a streamlined, convenience method when you don't need to chain call nor work with the promise API (for example, in routing).

In short:

• .then() - full power of the promise API but slightly more verbose
• .success() - doesn't return a promise but offeres slightly more convienient syntax

Some code examples for simple GET request. Maybe this helps understanding the difference. Using then:

$http.get('/someURL').then(function(response) {
    var data = response.data,
        status = response.status,
        header = response.header,
        config = response.config;
    // success handler
}, function(response) {
    var data = response.data,
        status = response.status,
        header = response.header,
        config = response.config;
    // error handler
});

Using success/error:

$http.get('/someURL').success(function(data, status, header, config) {
    // success handler
}).error(function(data, status, header, config) {
    // error handler
});