Source Notion: user-friendly connection error messages (#29999)

Co-authored-by: ChristoGrab <ChristoGrab@users.noreply.github.com>

airbyte-integrations/connectors/source-notion/Dockerfile

@@ -34,5 +34,5 @@ COPY source_notion ./source_notion
 ENV AIRBYTE_ENTRYPOINT "python /airbyte/integration_code/main.py"
 ENTRYPOINT ["python", "/airbyte/integration_code/main.py"]
 
-LABEL io.airbyte.version=1.1.1
+LABEL io.airbyte.version=1.1.2
 LABEL io.airbyte.name=airbyte/source-notion

airbyte-integrations/connectors/source-notion/metadata.yaml

@@ -5,7 +5,7 @@ data:
   connectorSubtype: api
   connectorType: source
   definitionId: 6e00b415-b02e-4160-bf02-58176a0ae687
-  dockerImageTag: 1.1.1
+  dockerImageTag: 1.1.2
   dockerRepository: airbyte/source-notion
   githubIssueLabel: source-notion
   icon: notion.svg

airbyte-integrations/connectors/source-notion/source_notion/source.py

@@ -41,7 +41,22 @@ class SourceNotion(AbstractSource):
             next(records)
             return True, None
         except requests.exceptions.RequestException as e:
-            return False, e
+            # The most likely user error will be incorrectly configured credentials. We can provide a specific error message for those cases. Otherwise, the stock Notion API message should suffice.
+            error_code = e.response.json().get("code")
+            if error_code == "unauthorized":
+                return (
+                    False,
+                    "The provided API access token is invalid. Please double-check that you input the correct token and have granted the necessary permissions to your Notion integration.",
+                )
+            if error_code == "restricted_resource":
+                return (
+                    False,
+                    "The provided API access token does not have the correct permissions configured. Please double-check that you have granted all the necessary permissions to your Notion integration.",
+                )
+            return (
+                False,
+                f"{e.response.json().get('message', 'An unexpected error occured while connecting to Notion. Please check your credentials and try again.')}",
+            )
 
     def streams(self, config: Mapping[str, Any]) -> List[Stream]:
         AirbyteLogger().log("INFO", f"Using start_date: {config['start_date']}")

airbyte-integrations/connectors/source-notion/unit_tests/test_source.py

@@ -4,8 +4,14 @@
 
 from unittest.mock import MagicMock
 
+import pytest
 from source_notion.source import SourceNotion
 
+UNAUTHORIZED_ERROR_MESSAGE = "The provided API access token is invalid. Please double-check that you input the correct token and have granted the necessary permissions to your Notion integration."
+RESTRICTED_RESOURCE_ERROR_MESSAGE = "The provided API access token does not have the correct permissions configured. Please double-check that you have granted all the necessary permissions to your Notion integration."
+GENERIC_ERROR_MESSAGE = "Conflict occured while saving. Please try again."
+NO_ERROR_MESSAGE = "An unexpected error occured while connecting to Notion. Please check your credentials and try again."
+
 
 def test_check_connection(mocker, requests_mock):
     source = SourceNotion()
@@ -14,6 +20,25 @@ def test_check_connection(mocker, requests_mock):
     assert source.check_connection(logger_mock, config_mock) == (True, None)
 
 
+@pytest.mark.parametrize(
+        "status_code,json_response,expected_message",
+        [
+            (401, {"code": "unauthorized"}, UNAUTHORIZED_ERROR_MESSAGE),
+            (403, {"code": "restricted_resource"}, RESTRICTED_RESOURCE_ERROR_MESSAGE),
+            (409, {"message": GENERIC_ERROR_MESSAGE}, GENERIC_ERROR_MESSAGE),
+            (400, {}, NO_ERROR_MESSAGE)
+        ]
+)
+def test_check_connection_errors(mocker, requests_mock, status_code, json_response, expected_message):
+    source = SourceNotion()
+    logger_mock, config_mock = MagicMock(), MagicMock()
+    requests_mock.get("https://api.notion.com/v1/users", status_code=status_code, json=json_response)
+    result, message = source.check_connection(logger_mock, config_mock)
+
+    assert result is False
+    assert message == expected_message
+
+
 def test_streams(mocker):
     source = SourceNotion()
     config_mock = MagicMock()

docs/integrations/sources/notion.md

@@ -107,6 +107,7 @@ The connector is restricted by Notion [request limits](https://developers.notion
 
 | Version | Date       | Pull Request                                             | Subject                                                                      |
 | :------ | :--------- | :------------------------------------------------------- | :--------------------------------------------------------------------------- |
+| 1.1.2   | 2023-08-30 | [29999](https://github.com/airbytehq/airbyte/pull/29999) | Update error handling during connection check
 | 1.1.1   | 2023-06-14 | [26535](https://github.com/airbytehq/airbyte/pull/26535) | Migrate from deprecated `authSpecification` to `advancedAuth`                |
 | 1.1.0   | 2023-06-08 | [27170](https://github.com/airbytehq/airbyte/pull/27170) | Fix typo in `blocks` schema                                                  |
 | 1.0.9   | 2023-06-08 | [27062](https://github.com/airbytehq/airbyte/pull/27062) | Skip streams with `invalid_start_cursor` error                               |