fix(vercel): distinguish transient errors from a bad token on validation

[Gilbert09]

Problem

When you add a Vercel source, we validate the access token with a GET /v2/user probe. The check split responses three ways: 200 passes, 401/403 says "invalid or unauthorized token", and everything else fell into:

Couldn't validate your Vercel access token. Check that it's a valid token from your Vercel account settings, then try again.

So a 429 rate limit, a Vercel 5xx, or a transient blip all told the user their token was the problem. On a network failure (requests.exceptions.RequestException) it was worse: we returned str(e) straight to the wizard, leaking the raw exception (which embeds the request URL) and giving the user nothing to act on.

These are transient, Vercel-side conditions. The token may be perfectly valid, so pointing the user at their credentials sends them chasing a fix that does not exist.

Changes

validate_credentials now treats 429, any 5xx, and network/timeout exceptions as transient and returns a single retry message instead:

Couldn't reach Vercel to validate your access token. Please try again in a few minutes.

401/403 (genuine auth failure) and the "check your token" fallback for other 4xx are unchanged. This mirrors how the sync path in the same module already classifies 429/5xx as retryable via VercelRetryableError.

How did you test this code?

Automated, in products/warehouse_sources/backend/temporal/data_imports/sources/vercel/tests/test_vercel.py:

• Reworked the network-exception test to assert we return the retry message and no longer leak the raw exception string. Guards the str(e) leak regression.
• Added a parameterized case over 429 / 500 / 503 asserting they return the retry message and not the "check your token" advice. Guards the core regression this PR fixes: transient statuses collapsing back into bad-token wording.

Ran the validation tests locally (9 passed) and ruff over the touched files. I (Claude) did not exercise this against the live Vercel API.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

🤖 Agent context

Autonomy: Fully autonomous

Written by Claude while triaging data-warehouse source-creation validation failures. Vercel stood out because every failing attempt landed on the generic "check your token" message even though 401/403 has its own branch, which meant the failures were non-auth (5xx/429/network) yet worded as auth problems.

Invoked /writing-tests before touching the test file. Scoped deliberately narrow: only the validation-probe copy/classification changed, no sync or schema behavior.

---

Created with PostHog Code

[trunk-io]

Merging to master in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[github-actions]

Hey @Gilbert09! 👋

It looks like your git author email on this PR isn't your @posthog.com address (owerstom@gmail.com). Since you're on the PostHog team, it's worth pointing your local git author email at your @posthog.com address. Why it matters:

• Consistent work identity in git history — internal tooling that attributes commits to team members keys off your @posthog.com address.
• Keeps team contributions easy to tell apart from external community ones when scanning history.

You can fix it for this repo with:

git config user.email "you@posthog.com"

Or set it globally with git config --global user.email "you@posthog.com". No need to redo this PR — just a nudge for next time. 🙂

[Copilot]

Pull request overview

This PR improves the Vercel warehouse source token validation UX by distinguishing transient Vercel/network failures from genuine authentication errors, so users aren’t incorrectly told their token is invalid when Vercel is rate-limiting or down.

Changes:

• Return a single retry-oriented message for network/timeout errors and transient HTTP statuses (429, 5xx) during GET /v2/user token validation.
• Stop returning the raw requests exception string to the wizard (avoids leaking low-level error details).
• Add/adjust unit tests to lock in the transient-status and request-exception behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
products/warehouse_sources/backend/temporal/data_imports/sources/vercel/vercel.py	Adds a shared “Vercel unreachable/transient error” message and uses it for request exceptions, 429, and 5xx in validate_credentials.
products/warehouse_sources/backend/temporal/data_imports/sources/vercel/tests/test_vercel.py	Updates validation tests to assert transient conditions return the retry message and do not leak raw exception text.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[stamphog]

Contained error-classification fix in Vercel token validation (distinguishes transient 429/5xx/network errors from a bad token, stops leaking raw exception text); owning-team author, tests cover the regression, no unresolved review concerns.

• Author wrote 0% of the modified lines and has 7 merged PRs in these paths (familiarity MODERATE).
• copilot-pull-request-reviewer[bot] reviewed the current head.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	15L, 1F substantive, 34L/2F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1b-small (34L, 2F, single-area, fix)
stamphog 2.0.0b4		.stamphog/policy.yml @ 96e2437 · reviewed head 6d6d810