What is the difference between "dismiss" a modal and "close" a modal in Angular UI-Bootstrap?

What is the difference between "dismiss" a modal and "close" a modal?

close(result) - a method that can be used to close a modal, passing a result
dismiss(reason) - a method that can be used to dismiss a modal, passing a reason

The answer is in the documentation, right after the two lines you quoted:

The open method returns a modal instance, an object with the following properties:

• close(result) - a method that can be used to close a modal, passing a result
• dismiss(reason) - a method that can be used to dismiss a modal, passing a reason
• result - a promise that is resolved when a modal is closed and rejected when a modal is dismissed

The important bit here being what happens to the promise. On close, the promise is resolved - essentially, the "success" callback fires. On dismiss, the promise is rejected, therefore running the "failure" callback instead.

I found that the dismissing of a modal is best to use if it is from a user closing the modal (e.g. returning to the state behind the modal and invoking state.go('^')), and the closing of the modal is used when changing state via $state.go or ui-sref.

That way you can use the result promise to do different things, depending on the what happens.

result.then(function() { /* state change via ui-sref */ })

result.catch(function() { /* user closed modal */ })