2 files changed, 21 insertions, 2 deletions

diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
index c016de56..11bd1cd2 100644
--- a/doc/md/REST-API.md
+++ b/doc/md/REST-API.md
@@ -152,3 +152,22 @@ See the reference API client:
 
 - [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
 - [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github
+
+## Troubleshooting
+
+### Debug mode
+
+> This should never be used in a production environment.
+
+For security reasons, authentication issues will always return an `HTTP 401` error code without any detail.
+
+It is possible to enable the debug mode in `config.json.php` 
+to get the actual error message in the HTTP response body with:
+
+```json
+{
+  "dev": {
+    "debug": true
+  }
+}
+```
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index 451ca36d..d5682a34 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -27,7 +27,7 @@ As all user data is kept under `data`, this is the only directory you need to wo
 
 - backup the `data` directory
 - install or update Shaarli:
-    - fresh installation - see [Download and installation](Download-and-installation)
+    - fresh installation - see [Download and Installation](Download-and-Installation)
     - update - see the following sections
 - check or restore the `data` directory
 
@@ -35,7 +35,7 @@ As all user data is kept under `data`, this is the only directory you need to wo
 
 All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
 
-We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation) for `git` complete instructions.
+We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and Installation](Download-and-Installation) for `git` complete instructions.
 
 Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!