Skip to content

: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.

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.py
index 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[st
session = _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[st
if 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[st
if 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 so
diff --git a/products/warehouse_sources/sources/polar/source.py b/products/warehouse_sources/sources/polar/source.py
index 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.register
class 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, None
except 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 None
if 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_MESSAGE
if 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_MESSAGE
return (
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.py
index 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 parameterized
from products.warehouse_sources.sources.polar import polar as polar_module
from 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, PolarSource
from products.warehouse_sources.sources.sdk import DEFAULT_RETRY
from 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_error
class TestPolarApiVersion: