:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
fix(data-warehouse): tell polar users which token scope to add (#130605)
Tom Owers6403730b950a
diff --git a/products/warehouse_sources/sources/polar/polar.py b/products/warehouse_sources/sources/polar/polar.pyindex 6f58069e7385..4ca60342730c 100644--- a/products/warehouse_sources/sources/polar/polar.py+++ b/products/warehouse_sources/sources/polar/polar.py@@ -26,6 +26,12 @@ class PolarResumeConfig:next_url: str+NO_READABLE_SCOPE_MESSAGE = (+ "Your Polar Organization Access Token can't read any of the data this source syncs. "+ "Create a token with the read scopes listed in the setup instructions, then reconnect."+)++class PolarPermissionError(Exception):pass@@ -140,7 +146,7 @@ def validate_credentials(api_key: str, api_version: str, table_name: Optional[stsession = _get_polar_session()# When called per-schema (the incremental_fields action), a 403 should surface- # immediately so the wizard can show "missing permissions for <endpoint>".+ # immediately so the wizard can name the scope that endpoint needs.# When called at source-create (no table_name), the user may legitimately have# scopes for only a subset of endpoints, so we accept any single non-403# response as proof of a usable token. Per-endpoint scope checks are deferred@@ -172,7 +178,10 @@ def validate_credentials(api_key: str, api_version: str, table_name: Optional[stif is_create_probe:forbidden.append(endpoint)continue- raise PolarPermissionError(f"Missing permissions for {endpoint}")+ raise PolarPermissionError(+ f"Your Polar Organization Access Token can't read {endpoint}. "+ f"Create a token with the {endpoint}:read scope, then reconnect."+ )if is_create_probe:# First non-403 success is proof enough — stop probing so a transient# 5xx on a later endpoint can't block source creation.@@ -186,9 +195,7 @@ def validate_credentials(api_key: str, api_version: str, table_name: Optional[stif is_create_probe:if forbidden and not last_failure:- raise PolarPermissionError(- f"token has no readable scope for any supported endpoint ({', '.join(forbidden)})"- )+ raise PolarPermissionError(NO_READABLE_SCOPE_MESSAGE)if last_failure is not None:# Only transient errors (and possibly some 403s) — no endpoint# confirmed the token works. Surface the underlying HTTP error sodiff --git a/products/warehouse_sources/sources/polar/source.py b/products/warehouse_sources/sources/polar/source.pyindex 36c80f456c25..cf142cf51a09 100644--- a/products/warehouse_sources/sources/polar/source.py+++ b/products/warehouse_sources/sources/polar/source.py@@ -29,6 +29,14 @@ from products.warehouse_sources.sources.sdk import (detect,)+INVALID_TOKEN_MESSAGE = (+ "Your Polar Organization Access Token is invalid or expired. Create a new token in Polar, then reconnect."+)+MISSING_SCOPE_MESSAGE = (+ "Your Polar Organization Access Token is missing a read scope this source needs. "+ "Create a token with the read scopes listed in the setup instructions, then reconnect."+)+@SourceRegistry.registerclass PolarSource(ResumableSource[PolarSourceConfig, PolarResumeConfig]):@@ -90,8 +98,8 @@ class PolarSource(ResumableSource[PolarSourceConfig, PolarResumeConfig]):def get_non_retryable_errors(self) -> dict[str, str | None]:return {- "401 Client Error: Unauthorized for url: https://api.polar.sh": "Your Polar Organization Access Token is invalid or expired. Please generate a new token in Polar and reconnect.",- "403 Client Error: Forbidden for url: https://api.polar.sh": "Your Polar Organization Access Token does not have the required permissions. Please check the token's scopes in Polar and reconnect.",+ "401 Client Error: Unauthorized for url: https://api.polar.sh": INVALID_TOKEN_MESSAGE,+ "403 Client Error: Forbidden for url: https://api.polar.sh": MISSING_SCOPE_MESSAGE,# Polar answers a removed or unknown `Polar-Version` with a 404; the list endpoints are static."404 Client Error: Not Found for url: https://api.polar.sh": "The Polar API version this source uses is no longer supported by Polar. Please contact support to move it to a newer version.",}@@ -118,21 +126,15 @@ class PolarSource(ResumableSource[PolarSourceConfig, PolarResumeConfig]):validate_polar_credentials(config.polar_api_key, self.resolve_api_version(api_version), schema_name)return True, Noneexcept PolarPermissionError as e:- return False, f"Polar Organization Access Token lacks permissions: {e}"+ return False, str(e)except requests.exceptions.HTTPError as e:# A failed probe surfaces via raise_for_status(): its str() leaks the full request URL# (with query params) and tells the user nothing to act on. Map the status instead.status_code = e.response.status_code if e.response is not None else Noneif status_code == 401:- return (- False,- "Your Polar Organization Access Token is invalid or expired. Please generate a new token in Polar and reconnect.",- )+ return False, INVALID_TOKEN_MESSAGEif status_code == 403:- return (- False,- "Your Polar Organization Access Token does not have the required permissions. Please check the token's scopes in Polar and reconnect.",- )+ return False, MISSING_SCOPE_MESSAGEreturn (False,f"Polar returned an unexpected error (HTTP {status_code}) while validating your token. Please try again.",diff --git a/products/warehouse_sources/sources/polar/test_polar_source.py b/products/warehouse_sources/sources/polar/test_polar_source.pyindex 53c97543ef86..65758b89f168 100644--- a/products/warehouse_sources/sources/polar/test_polar_source.py+++ b/products/warehouse_sources/sources/polar/test_polar_source.py@@ -8,7 +8,9 @@ from parameterized import parameterizedfrom products.warehouse_sources.sources.polar import polar as polar_modulefrom products.warehouse_sources.sources.polar._config import PolarSourceConfig-from products.warehouse_sources.sources.polar.source import PolarSource+from products.warehouse_sources.sources.polar.polar import NO_READABLE_SCOPE_MESSAGE+from products.warehouse_sources.sources.polar.settings import ENDPOINTS+from products.warehouse_sources.sources.polar.source import INVALID_TOKEN_MESSAGE, PolarSourcefrom products.warehouse_sources.sources.sdk import DEFAULT_RETRYfrom products.warehouse_sources.sources.sdk.testing import error_message_matches@@ -90,15 +92,45 @@ class TestPolarRetryableErrors:class TestPolarValidateCredentials:- def test_invalid_token_maps_401_without_leaking_url(self) -> None:+ @parameterized.expand(+ [+ ("connect_invalid_token", None, [401] * len(ENDPOINTS), False, INVALID_TOKEN_MESSAGE),+ ("connect_no_readable_scope", None, [403] * len(ENDPOINTS), False, NO_READABLE_SCOPE_MESSAGE),+ ("connect_one_readable_scope_is_enough", None, [403, 403, 200], True, None),+ (+ "connect_forbidden_then_invalid_token",+ None,+ [403] + [401] * (len(ENDPOINTS) - 1),+ False,+ INVALID_TOKEN_MESSAGE,+ ),+ (+ "table_missing_its_scope",+ "orders",+ [403],+ False,+ "Your Polar Organization Access Token can't read orders. "+ "Create a token with the orders:read scope, then reconnect.",+ ),+ ("table_invalid_token", "orders", [401], False, INVALID_TOKEN_MESSAGE),+ ]+ )+ def test_maps_probe_failures_to_actionable_messages(+ self,+ _name: str,+ schema_name: Optional[str],+ statuses: list[int],+ expected_ok: bool,+ expected_error: Optional[str],+ ) -> None:session = MagicMock()- session.request.return_value = _FakeResponse(401)+ session.request.side_effect = [_FakeResponse(status) for status in statuses]with patch.object(polar_module, "_get_polar_session", return_value=session):- ok, error = PolarSource().validate_credentials(PolarSourceConfig(polar_api_key="polar_oat_test"), team_id=1)- assert ok is False- assert error is not None- assert "api.polar.sh" not in error- assert "invalid or expired" in error+ ok, error = PolarSource().validate_credentials(+ PolarSourceConfig(polar_api_key="polar_oat_test"), team_id=1, schema_name=schema_name+ )+ assert ok is expected_ok+ assert error == expected_errorclass TestPolarApiVersion: