fix(oauth): improve refresh-token error message; remove 'please' and dead placeholder

[devin-ai-integration]

Summary

The CDK's AbstractOauth2Authenticator._make_handled_request (used by DeclarativeOauth2Authenticator and every other source that talks to an OAuth refresh endpoint) surfaces this user-facing string when the refresh response matches the configured refresh-token error indicators:

Refresh token is invalid or expired. Please re-authenticate from Sources/<your source>/Settings.

That string violates the writing-good-error-messages guidelines on multiple counts. This PR replaces it with a narrower, deterministic message and keeps useful detail in internal_message.

Specific problems with the current message:

• Embedded remediation: Please re-authenticate from Sources/<your source>/Settings. violates the rule that remediation belongs in docs / UI rather than embedded as a sentence in the user-facing string. The wording is also brittle (it references a specific UI navigation path).
• "Please" / emotional language: Violates the "no emotional language" rule.
• Over-claim of cause: The handler decides the token is "invalid or expired" based purely on a configured 4xx + error key/value match. Some upstream providers (e.g. Gong's generate-customer-token, tracked in airbytehq/airbyte-internal-issues#16467) return a matching 400 when the refresh request is malformed even though the refresh token itself is still valid. In that case telling the user to re-authenticate is a dead-end.
• Unsubstituted placeholder: The literal <your source> reaches end users instead of being replaced with the actual connector name.
• internal_message == message: No additional developer-facing detail is captured; HTTP status code in particular is useful when debugging logs.

Change:

• message → "OAuth token refresh failed with a refresh-token error response." — declarative, names the failing operation, doesn't over-claim the cause, no remediation embedded.
• internal_message → includes the HTTP status code and a pointer to the existing DEBUG-level token-refresh log (emitted via _log_response) for the full response body.
• failure_type is unchanged (config_error) since the common true-positive case (genuinely expired/invalid refresh token) still requires the user to re-authenticate.

Updated the corresponding parametrized assertion in unit_tests/.../test_requests_native_auth.py::TestOauth2Authenticator::test_refresh_access_token_wrapped.

This is a CDK-level message-only change — no schema / state / spec changes, so a patch version bump is appropriate. The upstream Gong root cause is a separate fix tracked in airbytehq/airbyte-internal-issues#16467 / draft PR airbytehq/airbyte-python-cdk#919.

Resolves https://github.com/airbytehq/airbyte-internal-issues/issues/16468

Review & Testing Checklist for Human

• Confirm the new message text is acceptable per writing-good-error-messages. Note the deliberate omission of an embedded remediation hint — see the false-positive discussion in airbytehq/airbyte-internal-issues#16468.
• Spot-check that no downstream connector or platform code greps for the old literal string "Refresh token is invalid or expired". A repo-wide search of airbytehq/airbyte and airbytehq/airbyte-python-cdk came up empty, but the platform / UI repos were not exhaustively searched.
• Sanity-check that surfacing the HTTP status code in internal_message is acceptable. The refresh response body is intentionally NOT included in internal_message (still logged at DEBUG via _log_response) to avoid potentially leaking client_id / scope hints into the structured exception.

Notes

• Patch-version-only change; no breaking-change metadata required.
• Coordination: draft PR airbytehq/airbyte-python-cdk#960 also targets OAuth error messages in DeclarativeOauth2Authenticator, but on a different code path (not abstract_oauth.py:308). No overlap.

Link to Devin session: https://app.devin.ai/sessions/b2160548fe034336ab68aba9f1eee15b

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@devin/1780092283-fix-oauth-refresh-error-message#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch devin/1780092283-fix-oauth-refresh-error-message

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /autofix - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test - Runs connector tests with the updated CDK
• /prerelease - Triggers a prerelease publish with default arguments
• /poe build - Regenerate git-committed build artifacts, such as the pydantic models which are generated from the manifest JSON schema in YAML.
• /poe <command> - Runs any poe command in the CDK environment

📚 Show Repo Guidance

Helpful Resources

• CDK API Reference

📝 Edit this welcome message.

[github-actions]

PyTest Results (Fast)

4 094 tests  ±0   4 083 ✅ ±0   8m 19s ⏱️ -7s
    1 suites ±0      11 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 0699540. ± Comparison against base commit a7b0929.

[github-actions]

PyTest Results (Full)

4 097 tests  ±0   4 085 ✅ ±0   11m 49s ⏱️ +12s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 0699540. ± Comparison against base commit a7b0929.

[Baz (bazarnov)]

Closing as superseded. The goals here (drop "please" and the dead <your source> placeholder, keep message distinct from internal_message, put the status code in the internal message) shipped in #1130, and #1138 extends that message with the provider's own error / error_description. The Gong case from this description, a 400 on a malformed refresh request while the token is still valid, is exactly what the appended provider detail makes diagnosable.

[devin-ai-integration]

❌ Cannot revive Devin session - the session is too old. Please start a new session instead.

View session