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(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.py
index 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.py
index 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.m
META_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.py
index 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.m
META_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.