From 471046d2a3db233298dcdd3bb4649a4904c75dad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89milien=20=28perso=29?=
 <4016501+unixfox@users.noreply.github.com>
Date: Sun, 10 Nov 2024 21:30:52 +0100
Subject: [PATCH] document youtube errors with solutions (#612)

---
 docs/faq.md                      |  3 ++
 docs/youtube-errors-explained.md | 49 ++++++++++++++++++++++++++++++++
 mkdocs.yml                       |  1 +
 3 files changed, 53 insertions(+)
 create mode 100644 docs/youtube-errors-explained.md

diff --git a/docs/faq.md b/docs/faq.md
index 674ab06..0d8985c 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -137,6 +137,9 @@ sent by your browser.
 
 **A:** This problem can occur in different scenarios:
 
+* If you are the one that have installed Invidious, please read the page
+  ["All the YouTube error messages explained with solutions"](/youtube-errors-explained/)
+
 * If you're trying to watch a music clip, Youtube is likely blocking the
   video stream. Try enabling `Proxy videos` in the preferences (or add
   `&local=1` in the URL). Switching to another instance is also a good
diff --git a/docs/youtube-errors-explained.md b/docs/youtube-errors-explained.md
new file mode 100644
index 0000000..ef5beb6
--- /dev/null
+++ b/docs/youtube-errors-explained.md
@@ -0,0 +1,49 @@
+# All the YouTube error messages explained with solutions
+
+**DISCLAIMER**: If you are just an user of a public instance. This documentation is not for you. Please instead redirect your Invidious instance maintainer to this page or switch to another public instance: [https://instances.invidious.io](https://instances.invidious.io)
+
+## Error: non 200 status code. Youtube API returned status code 429
+
+### Error explained
+
+YouTube is limiting the traffic that you can sent to their servers. This error may appear for a duration of 24 hours.
+
+### Cause(s)
+
+Usually it is related to a lot of traffic being generated for refreshing your subscriptions.
+
+- You have modified the parameter `channel_refresh_interval` and thus you are forcing the refresh of your subscriptions too quickly for YouTube.
+- You are subscribed to a lot of channels. YouTube may classify this as abuse due to Invidious having to check for new videos on a lot of channels.
+- You have sent a lot of traffic in another manner. Like by using the Invidious API.
+- Someone on your network is sending a lot of traffic to YouTube.
+
+### Solution(s)
+
+- Try to keep the `channel_refresh_interval` parameter commented to let Invidious refreshing your subscriptions less frequently.
+- Unsubscribe from some channels. While this may not be ideal, this will definitively send less data to YouTube.
+- Configure pubsub: [/installation/#post-install-configuration](/installation/#post-install-configuration). This requires your Invidious to be available on the internet and through a public domain.  
+   After this you can try to extend the refresh interval, like to `channel_refresh_interval: 240m`.  
+   You will still get almost instantaneous notifications from new YouTube videos thanks to pubsub but you will induce less refreshing traffic to YouTube servers. As pubsub is method for YouTube to notify your Invidious instance for new videos.
+- Change your public IP address. This may not solve the issue permanently but temporarily solve it.
+
+## Sign in to confirm you are not a bot - This helps protect our community
+
+### Error explained
+
+YouTube is blocking the communication of Invidious to their servers.
+
+### Cause(s)
+
+- YouTube is running different mechanisms to detect the usage of non official YouTube clients. Your Invidious instance may have been detected by their system.
+- Your IP address is blacklisted from YouTube servers. It is known that YouTube block datacenter IP addresses.
+
+### Solution(s)
+
+First make sure that you are running the latest version of Invidious and you are using inv_sig_helper. Please see [the updated installation guide](/installation/).
+
+After which you can try these solutions:
+
+- Change your public IP address. Reboot your router or by configuring a proxy in Invidious: https://github.com/iv-org/invidious/blob/2150264d849771df8f15bab172ab6d87eeb80c55/config/config.example.yml#L176-L185
+- If you have IPv6 on the computer hosting Invidious, you can try to rotate your IPv6 public address, tutorial available here: "[Rotate your IPv6 address for escaping YouTube blocking](/ipv6-rotator/)"
+
+All of these options do not guarantee you to bring back Invidious to working conditions. These are just advices for trying to unblock your Invidious instance from YouTube. Make sure to always specify any modification being done to your Invidious when reporting issues.
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 855b177..92bd3e0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -24,6 +24,7 @@ nav:
   - 'For Administrators':
     - 'installation.md'
     - 'configuration.md'
+    - 'youtube-errors-explained.md'
     - 'nginx.md'
     - 'caddy.md'
     - 'apache2.md'