I got a little confused by those docs too, and made a mental note to go back and see if I could figure out the difference.
But about the “only use very rarely”, I feel confident shedding some light on that.
Maybe someone will come along and correct me, but I believe that the Elixir ecosystem is fairly opinionated (in a good way) about not catching exceptions/errors. 95% of the time we should just ignore them and let them crash the app. Then, we look at the crashes, which should be only due to programming errors, and fix our bugs.
Said differently, The exceptions are generally things outside of our control that we can’t really program for. And: this is how we should design our own code: to use {:ok, :error} for business logic errors, and reaching for raising exceptions for unsalvageable inconsistencies.
