: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(meta-ads): show the specific reason when meta refuses the connection (#121032)
Tom Owers6b4e93f9757a
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/meta_ads.py b/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/meta_ads.pyindex 6b70ffdb1cf5..bc8fb7da1648 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/meta_ads.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/meta_ads.py@@ -484,6 +484,15 @@ META_AUTH_ERROR_MESSAGE = ("Meta Ads access token is invalid, expired, or lacks the required permissions. Please re-authorize the integration.")+# Code 190 / subcode 459: Meta has checkpointed the user behind the token. The token stays refused+# until that user signs in to Facebook and clears the check, which reconnecting alone doesn't do.+META_CHECKPOINT_ERROR_SUBCODE = 459++META_CHECKPOINT_ERROR_MESSAGE = (+ "Meta locked the Facebook account you connected until it passes a security check. Sign in at "+ "facebook.com, follow the steps, then reconnect your Meta Ads account."+)+META_RATE_LIMIT_ERROR_MESSAGE = ("Meta is rate limiting requests for this connection. Please wait a few minutes and try again.")@@ -595,7 +604,12 @@ def _raise_meta_api_error(response: Response) -> typing.NoReturn:Everything else raises the raw response and stays retryable."""if _is_permanent_auth_error(response):- raise Exception(f"{META_AUTH_ERROR_MESSAGE} (Meta API response: {response.status_code} - {response.text})")+ message = (+ META_CHECKPOINT_ERROR_MESSAGE+ if _meta_error_subcode(response) == META_CHECKPOINT_ERROR_SUBCODE+ else META_AUTH_ERROR_MESSAGE+ )+ raise Exception(f"{message} (Meta API response: {response.status_code} - {response.text})")if _is_rate_limit_error(response):raise Exception(f"{META_RATE_LIMIT_ERROR_MESSAGE} (Meta API response: {response.status_code} - {response.text})"diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/source.pyindex 7dba1ea7f1cf..e1faf3c18a97 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/source.py@@ -45,6 +45,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.meta_ads.mMETA_ADS_API_VERSION_V25,META_ADS_API_VERSION_V26,META_AUTH_ERROR_MESSAGE,+ META_CHECKPOINT_ERROR_MESSAGE,META_INVALID_CURSOR_ERROR_MESSAGE,META_RATE_LIMIT_ERROR_MESSAGE,META_TOKEN_REFRESH_ERROR_MESSAGE,@@ -143,18 +144,14 @@ class MetaAdsSource(ResumableSource[MetaAdsSourceConfig, MetaAdsResumeConfig], O"Integration matching query does not exist.": ("The Meta Ads integration for this source no longer exists. Please reconnect the Meta Ads integration."),- # Permanent auth/permission failures from the Graph API (e.g. revoked or expired- # access tokens, checkpoint-required, invalidated sessions, permission denials).- # `meta_ads._raise_meta_api_error` prefixes these with this exact message.- META_AUTH_ERROR_MESSAGE: META_AUTH_ERROR_MESSAGE,+ META_CHECKPOINT_ERROR_MESSAGE: META_CHECKPOINT_ERROR_MESSAGE,# Graph API code 200: "Ad account owner has NOT granted ads_management or ads_read# permission." The connected Meta user can't read this ad account's data. Retrying# can't grant the permission — the account owner has to. Without a message here the# raw Graph API JSON blob surfaces to the user, so give actionable guidance instead."Ad account owner has NOT": (- "Meta denied access to this ad account — the connected Meta account is missing the "- "ads_read permission needed to sync its data. Ask the ad account owner to grant that "- "access, then reconnect the Meta Ads integration."+ "The Meta account you connected doesn't have ads_read access to this ad account. Ask "+ "the ad account owner to grant it, then reconnect your Meta Ads account."),# Graph API code 100: "This endpoint cannot be loaded due to missing permissions." A# specific endpoint can't be read with the permissions the user granted. Same as above:@@ -177,10 +174,8 @@ class MetaAdsSource(ResumableSource[MetaAdsSourceConfig, MetaAdsResumeConfig], O# `AD_ACCOUNT_FIELDS` in meta_ads.py). Only the account owner granting# `business_management`, or PostHog dropping the field that needs it, fixes this."Requires business_management permission": (- "Meta rejected part of this request because it needs the business_management "- "permission, which this integration does not request and cannot request without "- "widening OAuth consent for every customer. Re-authorizing will not fix this — "- "contact PostHog support if this table keeps failing."+ "Meta needs the business_management permission for part of this table, which PostHog "+ "doesn't request, so reconnecting won't fix it. Contact PostHog support about this table."),# Graph API code 100: the source's "Attribution windows for insights" setting (a# free-text field, see `SourceFieldInputConfig` above) contains a value Meta's@@ -221,6 +216,12 @@ class MetaAdsSource(ResumableSource[MetaAdsSourceConfig, MetaAdsResumeConfig], O"Choose date_start as the incremental field in the table's sync settings, or switch ""it to full refresh, then run the sync again."),+ # Permanent auth/permission failures from the Graph API (e.g. revoked or expired+ # access tokens, invalidated sessions, permission denials).+ # `meta_ads._raise_meta_api_error` prefixes these with this exact message. Last, because+ # the first matching entry supplies the message, and the code 200 entries above match+ # the same prefixed errors with more specific guidance.+ META_AUTH_ERROR_MESSAGE: META_AUTH_ERROR_MESSAGE,}def get_retryable_errors(self) -> set[str]:diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/test_meta_ads.py b/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/test_meta_ads.pyindex 309f58feaef7..205a3b7252a2 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/test_meta_ads.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/meta_ads/test_meta_ads.py@@ -42,6 +42,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.meta_ads.mMETA_ADS_API_VERSION_V26,META_ADS_MAX_HISTORY_DAYS,META_AUTH_ERROR_MESSAGE,+ META_CHECKPOINT_ERROR_MESSAGE,META_INVALID_CURSOR_ERROR_MESSAGE,META_RATE_LIMIT_ERROR_MESSAGE,META_TOKEN_REFRESH_ERROR_MESSAGE,@@ -1675,7 +1676,7 @@ class TestNonRetryableErrors:f"{SHRINK_EXHAUSTED_ERROR_MESSAGE} (Meta API response: 400 - "'{"error":{"message":"Service temporarily unavailable","code":2,"error_subcode":1504044}})',# code 190 / subcode 459 — account checkpoint, the user must log in to Facebook.- f"{META_AUTH_ERROR_MESSAGE} (Meta API response: 400 - "+ f"{META_CHECKPOINT_ERROR_MESSAGE} (Meta API response: 400 - "'{"error":{"message":"You cannot access the app till you log in to www.facebook.com and follow the ''instructions given.","type":"OAuthException","code":190,"error_subcode":459}})',# code 190 / subcode 460 — session invalidated after a password change.@@ -1697,6 +1698,46 @@ class TestNonRetryableErrors:f"Meta Ads error '{error_message}' does not match any non-retryable pattern")+ @pytest.mark.parametrize(+ "body,expected_pattern",+ [+ (+ {+ "error": {+ "message": "You cannot access the app till you log in to www.facebook.com and follow the instructions given.",+ "type": "OAuthException",+ "code": 190,+ "error_subcode": 459,+ }+ },+ META_CHECKPOINT_ERROR_MESSAGE,+ ),+ (+ {+ "error": {+ "message": "(#200) Ad account owner has NOT grant ads_management or ads_read permission",+ "type": "OAuthException",+ "code": 200,+ }+ },+ "Ad account owner has NOT",+ ),+ (+ {"error": {"message": "Error validating access token", "code": 190, "error_subcode": 460}},+ META_AUTH_ERROR_MESSAGE,+ ),+ ],+ )+ def test_auth_error_resolves_to_its_specific_message(self, body: dict, expected_pattern: str) -> None:+ response = _mock_response(400, body)+ response.text = json.dumps(body)+ with pytest.raises(Exception) as exc_info:+ _raise_meta_api_error(response)++ errors = MetaAdsSource().get_non_retryable_errors()+ first_match = next(pattern for pattern in errors if error_message_matches(str(exc_info.value), [pattern]))+ assert errors[first_match] == errors[expected_pattern]+def test_missing_perms_has_reconnect_guidance(self) -> None:# `error_message` isn't surfaced to the user as-is — the friendly value here is, so a# blank or wrong one would leak the raw Graph API JSON instead of actionable guidance.