From 5d7e9f3879abda7ebddb619d2b3dfe954e5d4a9c Mon Sep 17 00:00:00 2001
From: Lonami Exo <totufals@hotmail.com>
Date: Fri, 27 Dec 2019 11:27:00 +0100
Subject: [PATCH] Improve doc page on RPC errors (#1350)

---
 readthedocs/concepts/errors.rst | 87 +++++++++++++++++++++++++++++++--
 readthedocs/modules/errors.rst  |  3 +-
 2 files changed, 84 insertions(+), 6 deletions(-)

diff --git a/readthedocs/concepts/errors.rst b/readthedocs/concepts/errors.rst
index dc8d584c..94aad1e3 100644
--- a/readthedocs/concepts/errors.rst
+++ b/readthedocs/concepts/errors.rst
@@ -7,8 +7,59 @@ RPC Errors
 RPC stands for Remote Procedure Call, and when the library raises
 a ``RPCError``, it's because you have invoked some of the API
 methods incorrectly (wrong parameters, wrong permissions, or even
-something went wrong on Telegram's server). All the errors are
-available in :ref:`telethon-errors`, but some examples are:
+something went wrong on Telegram's server).
+
+You should import the errors from ``telethon.errors`` like so:
+
+.. code-block:: python
+
+    from telethon import errors
+
+    try:
+        async with client.takeout() as takeout:
+            ...
+
+    except errors.TakeoutInitDelayError as e:
+        #  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ here we except TAKEOUT_INIT_DELAY
+        print('Must wait', e.seconds, 'before takeout')
+
+
+There isn't any official list of all possible RPC errors, so the
+`list of known errors`_ is provided on a best-effort basis. When new methods
+are available, the list may be lacking since we simply don't know what errors
+can raise from them.
+
+Once we do find out about a new error and what causes it, the list is
+updated, so if you see an error without a specific class, do report it
+(and what method caused it)!.
+
+This list is used to generate documentation for the `raw API page`_.
+For example, if we want to know what errors can occur from
+`messages.sendMessage`_ we can simply navigate to its raw API page
+and find it has 24 known RPC errors at the time of writing.
+
+
+Base Errors
+===========
+
+All the "base" errors are listed in :ref:`telethon-errors`.
+Any other more specific error will be a subclass of these.
+
+If the library isn't aware of a specific error just yet, it will instead
+raise one of these superclasses. This means you may find stuff like this:
+
+.. code-block:: text
+
+    telethon.errors.rpcbaseerrors.BadRequestError: RPCError 400: MESSAGE_POLL_CLOSED (caused by SendVoteRequest)
+
+If you do, make sure to open an issue or send a pull request to update the
+`list of known errors`_.
+
+
+Common Errors
+=============
+
+These are some of the errors you may normally need to deal with:
 
 -  ``FloodWaitError`` (420), the same request was repeated many times.
    Must wait ``.seconds`` (you can access this attribute). For example:
@@ -26,9 +77,8 @@ available in :ref:`telethon-errors`, but some examples are:
            time.sleep(e.seconds)
 
 -  ``SessionPasswordNeededError``, if you have setup two-steps
-   verification on Telegram.
--  ``CdnFileTamperedError``, if the media you were trying to download
-   from a CDN has been altered.
+   verification on Telegram and are trying to sign in.
+-  ``FilePartMissingError``, if you have tried to upload an empty file.
 -  ``ChatAdminRequiredError``, you don't have permissions to perform
    said operation on a chat or channel. Try avoiding filters, i.e. when
    searching messages.
@@ -47,6 +97,28 @@ You can refer to all errors from Python through the ``telethon.errors``
 module. If you don't know what attributes they have, try printing their
 dir (like ``print(dir(e))``).
 
+
+Attributes
+==========
+
+Some of the errors carry additional data in them. When they look like
+``EMAIL_UNCONFIRMED_X``, the ``_X`` value will be accessible from the
+error instance. The current list of errors that do this is the following:
+
+- ``EmailUnconfirmedError`` has ``.code_length``.
+- ``FileMigrateError`` has ``.new_dc``.
+- ``FilePartMissingError`` has ``.which``.
+- ``FloodTestPhoneWaitError`` has ``.seconds``.
+- ``FloodWaitError`` has ``.seconds``.
+- ``InterdcCallErrorError`` has ``.dc``.
+- ``InterdcCallRichErrorError`` has ``.dc``.
+- ``NetworkMigrateError`` has ``.new_dc``.
+- ``PhoneMigrateError`` has ``.new_dc``.
+- ``SlowModeWaitError`` has ``.seconds``.
+- ``TakeoutInitDelayError`` has ``.seconds``.
+- ``UserMigrateError`` has ``.new_dc``.
+
+
 Avoiding Limits
 ===============
 
@@ -76,3 +148,8 @@ You can also except it and act as you prefer:
         quit(1)
 
 VoIP numbers are very limited, and some countries are more limited too.
+
+
+.. _list of known errors: https://github.com/LonamiWebs/Telethon/blob/master/telethon_generator/data/errors.csv
+.. _raw API page: https://tl.telethon.dev/
+.. _messages.sendMessage: https://tl.telethon.dev/methods/messages/send_message.html
diff --git a/readthedocs/modules/errors.rst b/readthedocs/modules/errors.rst
index 0df239c9..79a1243d 100644
--- a/readthedocs/modules/errors.rst
+++ b/readthedocs/modules/errors.rst
@@ -6,7 +6,8 @@ API Errors
 
 These are the base errors that Telegram's API may raise.
 
-See :ref:`rpc-errors` for a more friendly explanation.
+See :ref:`rpc-errors` for a more in-depth explanation on how to handle all
+known possible errors and learning to determine what a method may raise.
 
 .. automodule:: telethon.errors.common
     :members: