diff --git a/docs/getting-started/metadata-providers.md b/docs/getting-started/metadata-providers.md
index 1544ed4..6731c19 100644
--- a/docs/getting-started/metadata-providers.md
+++ b/docs/getting-started/metadata-providers.md
@@ -73,6 +73,12 @@ Note the client ID and secret that appear on screen, and use them to set `IGDB_C
 
 To access the ScreenScraper API, create a [ScreenScraper](https://www.screenscraper.fr/membreinscription.php) account and copy the **user** and **password** you just created to `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD` respectively.
 
+ScreenScraper's API also expects a second pair of **developer** credentials that identify the calling application, which RomM sends on every request alongside your user credentials. Our official Docker images have RomM's developer credentials baked in at build time, so there's nothing extra to set.
+
+<!-- prettier-ignore -->
+!!! important "Running RomM outside our official image"
+    Builds from source and third-party packages (such as the `romm` package in nixpkgs) ship without developer credentials, and ScreenScraper then rejects every request with `403 Forbidden`, which the scanner reports as `401: Invalid ScreenScraper credentials` even when `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD` are correct. Set `SCREENSCRAPER_DEV_ID` and `SCREENSCRAPER_DEV_PASSWORD` to a valid developer pair to fix it. ScreenScraper issues developer credentials to registered members on request, and the pair inside our official images is also usable. Either way, load them from a secret store or an env file rather than a world-readable config, and never commit them. Nothing else in RomM depends on them, so every other provider and feature keeps working while they're unset.
+
 ### MobyGames
 
 MobyGames is a metadata provider that offers metadata, cover art and screenshots.
diff --git a/docs/troubleshooting/scanning.md b/docs/troubleshooting/scanning.md
index 4bb8e18..91dae82 100644
--- a/docs/troubleshooting/scanning.md
+++ b/docs/troubleshooting/scanning.md
@@ -80,6 +80,17 @@ Options, in order of effort:
 2. **Use filename tags**: if you already know the provider ID, rename the file to include `(igdb-1234)` or similar (see [Metadata Providers → Filename tags](../getting-started/metadata-providers.md#metadata-tags-in-filenames)).
 3. **Manually match**: open the ROM detail page, click the **Match** button, and search for the right title.
 
+## ScreenScraper fails with 403 Forbidden
+
+```text
+ERROR:    [RomM][screenscraper]   403, message='Forbidden', url='https://api.screenscraper.fr/api2/jeuInfos.php?...'
+ERROR:    [RomM][scan]   401: Invalid ScreenScraper credentials
+```
+
+Despite the message, this usually isn't your account. ScreenScraper also requires developer credentials identifying the application, which our official Docker images supply at build time and builds from source or third-party packages don't, so set `SCREENSCRAPER_DEV_ID` and `SCREENSCRAPER_DEV_PASSWORD` and rerun the scan (see [ScreenScraper](../getting-started/metadata-providers.md#screenscraper)).
+
+If you're on an official image and still get 403s, re-check `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD`, then check whether you've exhausted your account's daily request quota.
+
 ## Hash calculations are slow
 
 Hashing large ROMs (PS1, Saturn, DC images) is IO-bound, with a few options: