fix(source-zendesk-chat): name Zendesk Chat and the access token in 401 errors

[devin-ai-integration]

What

When Zendesk rejects the credentials, source-zendesk-chat's check surfaced the CDK's generic default 401 text:

Stream routing_settings is not available: HTTP Status Code: 401. Error: Unauthorized. Please ensure you are authenticated correctly.

It names no vendor and no credential, and "Please ensure you are authenticated correctly." is exactly the vague remediation the error-message guidelines prohibit. Message-only fix; it now reads:

Stream routing_settings is not available: Zendesk Chat access token is invalid, expired, or missing the required read and chat scopes.

Related to https://github.com/airbytehq/oncall/issues/13227:

• https://github.com/airbytehq/oncall/issues/13227

Requested by the /ai-fix run on that oncall issue.

How

All 12 stream requesters in manifest.yaml carried an identical inline DefaultErrorHandler (404 IGNORE + Retry-After backoff). Instead of copying a new filter into 12 places, the handler is now a single definitions.error_handler that each requester $refs, with a 401 filter added:

error_handler:
  type: DefaultErrorHandler
  response_filters:
    - { http_codes: [404], action: IGNORE }
    - http_codes: [401]
      action: FAIL
      failure_type: config_error
      error_message: "Zendesk Chat access token is invalid, expired, or missing the required read and chat scopes."
  backoff_strategies:
    - { type: WaitTimeFromHeader, header: Retry-After }

404 IGNORE and the Retry-After backoff are unchanged for every stream.

Declarative-First Evaluation

Declarative only: the built-in HttpResponseFilter supports both error_message and failure_type, so no custom Python component was needed. Prior art: source-pinterest/manifest.yaml.

Test Coverage

New mock-server test test_401_error_has_connector_specific_message mocks a 401 on the check-probe endpoint and asserts the resulting AirbyteConnectionStatus message. Confirmed it fails against the parent commit's manifest (yielding the old CDK string) and passes here; full connector suite: 39 passed.

Additionally validated by the /ai-prove-fix run on this PR: a real 401 from Zendesk (invalid access token, shipped base image source-declarative-manifest:7.23.8) reproduced the old message on the master manifest and the new one here, with status staying FAILED/config_error; comparison regression tests against control 1.3.21 were identical on SPEC/CHECK/DISCOVER/READ with matching record counts across all 12 streams. Evidence is in the prove-fix comment below.

Known limitation (deliberately out of scope)

The Stream routing_settings is not available: prefix still leaks the internal check-probe stream name. That prefix comes from CheckStream._check_stream_availability in airbyte-python-cdk, and the generic 401 text it wrapped comes from that repo's default_error_mapping.py — both are cross-cutting changes affecting every declarative connector and are better proposed separately. OAuth refresh-token support (the deeper cause of these 401s, since the connector uses a static BearerAuthenticator) is tracked in https://github.com/airbytehq/oncall/issues/11261 with draft PR #73316; it is a breaking change, so this PR stays message-only.

Review guide

1. airbyte-integrations/connectors/source-zendesk-chat/manifest.yaml
2. airbyte-integrations/connectors/source-zendesk-chat/unit_tests/mock_server/test_routing_settings.py

User Impact

Users whose Zendesk Chat access token is invalid, expired, or under-scoped now see a message naming the vendor and the credential instead of generic "Unauthorized" text. No schema, spec, state, or behavior change — non-breaking patch bump 1.3.21 → 1.3.22.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

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

[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

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Note

Autopilot progressive rollouts are not enabled for the following modified connector(s):

• source-zendesk-chat

This is a courtesy heads-up only — it does not block merge or fail any check.
To enable automatic progressive rollouts for the connector(s) above, comment
/enable-autopilot-rollouts on this PR. This sets defaultRolloutMode: autopilot
and enableProgressiveRollout: true in each connector's metadata.yaml,
preserving any existing autopilotConfig.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-cxgby8fw0-airbyte-growth.vercel.app
Latest Commit:	a05ae82

Deployed with vercel-action

[github-actions]

source-zendesk-chat Connector Test Results

46 tests   42 ✅  31s ⏱️
 2 suites   4 💤
 2 files     0 ❌

Results for commit a05ae82.

♻️ This comment has been updated with latest results.

[Airbyte Support Bot (airbyte-support-bot)]

↪️ Triggering /ai-prove-fix per Hands-Free AI Triage Project triage next step.

Reason: Draft /ai-fix PR with green CI and no prove-fix run on record; validating the improved 401 error message is the next pipeline gate.

• https://github.com/airbytehq/oncall/issues/13227

Devin session

[octavia-bot]

🔍 AI Prove Fix session starting... Running readiness checks and testing against customer connections. View playbook

• 🔗 Session URL: https://app.devin.ai/sessions/eda51482af9c4386a754dbb9945c8a51

✅ Devin AI session created successfully!

[Airbyte Support Bot (airbyte-support-bot)]

🧪 Fix Validation Evidence

🟢 Outcome: Fix Proven

Reproduced the exact 401 this PR targets by running check with a deliberately invalid access token against a real Zendesk host, twice on the connector's shipped base image source-declarative-manifest:7.23.8 — once with the master manifest, once with this PR's. Zendesk returned a genuine 401 both times; the only variable was the manifest. Control emitted the generic CDK text quoted in the linked issue, target emitted the new Zendesk-specific message, and status stayed FAILED/config_error in both. Separately, comparison regression tests against control 1.3.21 came back ✅ on SPEC / CHECK / DISCOVER / READ with identical record counts across all 12 streams, confirming the 12-way error-handler $ref refactor is behavior-preserving.

🚦 Next Steps

1. This PR appears ready for review and merge (it is currently a draft — mark it ready when you're happy with it).
2. A pre-release 1.3.22-preview.a05ae82 is available if you want broader validation via /ai-canary-prerelease first, though for a message-only change that is likely unnecessary.
3. The daily_hands_free_triage automation will monitor the release rollout after merge.

---

📋 Connector & PR Details

Connector: source-zendesk-chat
PR: #83336 (head a05ae82)
Pre-release Version Tested: 1.3.22-preview.a05ae82 (regression tests build :dev directly from the PR)
Comparison Baseline: override_control_image=airbyte/source-zendesk-chat:1.3.21 — the version the linked issue reports as exhibiting the failure, which is also the current latest published version
Detailed Results: https://github.com/airbytehq/oncall/issues/13227#issuecomment-5178541633
Session: https://app.devin.ai/sessions/eda51482af9c4386a754dbb9945c8a51

📝 Evidence Plan

Hypothesis

Message-only change. The added 401 HttpResponseFilter (FAIL / config_error) matches how the CDK already classified 401s, so only the error string should change. The 404 IGNORE rule and Retry-After backoff in the new shared definitions.error_handler are identical to what each of the 12 requesters carried inline.

Proving criteria

1. On a real 401, check reports the Zendesk-specific message instead of HTTP Status Code: 401. Error: Unauthorized. Please ensure you are authenticated correctly. — observed on CHECK, the operation where the reported symptom manifests.
2. No behavioral difference elsewhere: SPEC / CHECK / DISCOVER / READ identical with valid credentials, no record-count drop on any of the 12 streams.

Disproving criteria

Old generic text persists; or the 401 is retried/ignored rather than failing; or any stream loses records, changes schema, or newly errors versus control.

Testing strategy decision

Regression tests + fault injection. No live customer connection pinning, and no candidate connections were selected — a healthy connection cannot produce a 401, so pinning could not have exercised criterion 1 and would have added customer risk for zero signal. Criterion 2 is exactly what comparison regression tests measure; this connector is a source with GSM integration-test credentials and is not on the forced-OAuth-write-back list (static BearerAuthenticator, no refresh_token_updater), so the sandbox was viable.

Cases attempted

1. 401 fault injection, master vs PR manifest on base image 7.23.8 → proved criterion 1. Control reproduced the issue's message character-for-character; target emitted the new one.
2. Regression tests, attempt 1 of 5: GSM creds, all streams, control 1.3.21 → proved criterion 2. All four verbs ✅; no retries needed.
3. Backup (unused): customer connection_id with all streams, per the playbook escalation table. Not needed — attempt 1 was informative.

✅ Pre-flight Checks

• Viability — the 401 filter produces the message the linked issue asked for; the shared handler reproduces the previous inline handler exactly, verified across all 12 requesters in the diff.
• Safety — no obfuscation, no new network calls, no credential handling. Manifest + one unit test + version bump + changelog only.
• Breaking Change: NO — no schema, primary-key, cursor, spec, stream, or state change. Patch bump 1.3.21 → 1.3.22 is correct; no breakingChanges entry or migration guide required.
• Pin Exclusion — N/A: no live pinning was performed and no candidate connections were queried or selected.
• Reversibility — YES. Message-only; 1.3.21 reads any state or config written by 1.3.22.

Design intent: not a concern. The generic 401 text was a CDK default rather than a deliberate source-zendesk-chat choice, and the 401 remains FAIL/config_error exactly as the CDK already classified it — the fix narrows wording without changing failure semantics.

📊 Detailed Evidence Log

Case 1 — 401 fault injection (real Zendesk 401, invalid token, check)

Control (master manifest):

{"type":"CONNECTION_STATUS","connectionStatus":{"status":"FAILED","message":"'Stream routing_settings is not available: HTTP Status Code: 401. Error: Unauthorized. Please ensure you are authenticated correctly.'"}}

Target (PR manifest, head a05ae82):

{"type":"CONNECTION_STATUS","connectionStatus":{"status":"FAILED","message":"'Stream routing_settings is not available: Zendesk Chat access token is invalid, expired, or missing the required read and chat scopes.'"}}

Zendesk's own response body was {'error': 'Unauthorized', 'description': 'The server could not verify that you are authorized to access the requested resource'}, served by zendesk-service: chat-scribe — a genuine upstream 401, not a mock. The same control string was also reproduced directly from the published airbyte/source-zendesk-chat:1.3.21 image, so it is not an artifact of the base-image harness.

Case 2 — comparison regression tests

Run: https://github.com/airbytehq/airbyte-ops-mcp/actions/runs/30905562179

Command	Result
SPEC	✅ no difference
CHECK	✅ no difference (SUCCEEDED both sides)
DISCOVER	✅ no difference
READ	✅ no difference

READ totals identical on both sides: 745 RECORD, 16 STATE, 36 TRACE, 75 LOG. Per-stream counts identical, all >0, so the shared error handler was exercised on every stream rather than only the check probe:

accounts 1 · agent_timeline 419 · agents 3 · bans 124 · chats 127 · departments 42 · goals 5 · roles 3 · routing_settings 1 · shortcuts 4 · skills 4 · triggers 12

Note on the pre-release publish

The first pre-release publish failed on a transient GitHub API 429 (https://github.com/airbytehq/airbyte/actions/runs/30905568068), unrelated to this PR; re-triggered as https://github.com/airbytehq/airbyte/actions/runs/30906111582. Neither piece of evidence above depended on that image.

No customer connections were involved in this validation, so there are no connection or workspace identifiers to redact.

---

Devin session

[github-actions]

Pre-release Connector Publish Started

Publishing pre-release build for connector source-zendesk-chat.
PR: #83336

Pre-release versions will be tagged as {version}-preview.a05ae82
and are available for version pinning via the scoped_configuration API.

View workflow run
❌ Pre-release Publish FAILED for source-zendesk-chat.

[github-actions]

Pre-release Connector Publish Started

Publishing pre-release build for connector source-zendesk-chat.
PR: #83336

Pre-release versions will be tagged as {version}-preview.a05ae82
and are available for version pinning via the scoped_configuration API.

View workflow run
❌ Pre-release Publish FAILED for source-zendesk-chat.

[Airbyte Support Bot (airbyte-support-bot)]

↪️ Triggering /ai-review per Hands-Free AI Triage Project triage next step.

Reason: /ai-prove-fix returned 🟢 Fix Proven on the current HEAD, so I marked the PR ready for review; an AI review is the next pipeline gate.

Devin session

[octavia-bot]

AI PR Review starting...

Reviewing PR for connector safety and quality.
View playbook

• 🔗 Session URL: https://app.devin.ai/sessions/c0bada788b844226883c460b246b67fa

✅ Devin AI session created successfully!

[Airbyte Support Bot (airbyte-support-bot)]

🛡️ AI PR Review Report

🟢 Review Action: APPROVED

Gate	Status
Behavioral Changes	FAIL (warning-level — does not block approval)

All other 11 gates passed.

⚠️ Risk Level: 4/5

Error-handler and backoff keywords in manifest.yaml (12-way error_handler $ref refactor + new 401 FAIL filter) trip the Behavioral Changes anti-pattern gate, which forces risk ≥ 4 — though /ai-prove-fix demonstrated the refactor is behavior-preserving.

---

📋 PR Details

Connector(s): source-zendesk-chat
PR: #83336
HEAD SHA: a05ae82698c33544a0d5e0d3eec31c29d3e66f7e
Session: https://app.devin.ai/sessions/c0bada788b844226883c460b246b67fa

🔍 Gate Evaluation Details

Gate-by-Gate Analysis

Gate	Status	Enforced?	Details
PR Hygiene	PASS	Yes	Description is substantive (~3.9k chars of real content, not template); docs/integrations/sources/zendesk-chat.md gains a 1.3.22 changelog row; zero human review comments (all 12 PR comments are from bots).
Code Hygiene	PASS	WARNING	Source (manifest.yaml) changed and a test file changed in the same PR (unit_tests/mock_server/test_routing_settings.py).
Test Coverage	PASS	Yes	Behavioral change (title starts fix(...)); new test content added: def test_401_error_has_connector_specific_message with a new assert on the AirbyteConnectionStatus message.
Code Security	PASS	Yes	No changed file matches the auth/credential/token path patterns; diff hunks in manifest.yaml contain none of authenticator, access_token, client_secret, api_key, etc. (the new prose string "access token" is not the access_token keyword), and the metadata.yaml hunk is only dockerImageTag: 1.3.21 → 1.3.22.
Per-Record Performance	PASS	WARNING	No record-processing code touched; the manifest change is confined to error_handler wiring, which runs on error responses only.
Breaking Dependencies	PASS	WARNING	No pyproject.toml, poetry.lock, or gradle dependency changes; base image unchanged.
Backwards Compatibility	PASS	Yes (enforced)	No spec file, no schemas/*.json, no stream add/remove/rename, no primary-key/cursor field or value change, no type/format change. metadata.yaml change is a patch dockerImageTag bump only, so no releases.breakingChanges entry is required.
Forwards Compatibility	PASS	Warning (elevates Risk Level)	No state/cursor/checkpoint/partition-router/paginator/transformation keyword appears in any added or removed line (occurrences of record_selector in the file are context lines outside the hunks' +/- content). No partition-key shape change.
Behavioral Changes	FAIL	Warning (elevates Risk Level)	Operational-risk keywords present in diff hunks of manifest.yaml: error_handler, response_filters, HttpResponseFilter, http_codes, backoff_strategies, Retry-After. Mitigations on record: the removed inline handlers and the new shared definitions.error_handler are identical for 404 IGNORE and Retry-After backoff; the only semantic addition is a 401 → FAIL/config_error filter with a connector-specific message; and /ai-prove-fix comparison regression tests vs. control 1.3.21 were identical on SPEC/CHECK/DISCOVER/READ with matching record counts across all 12 streams.
Out-of-Scope Changes	PASS	Skip	All 4 changed files are in scope: 3 under airbyte-integrations/connectors/source-zendesk-chat/** and 1 under docs/.
CI Checks	PASS	Yes	Core checks on this SHA are green, including the re-run triggered when the PR was marked ready: Test source-zendesk-chat Connector, Lint source-zendesk-chat Connector, Build and Verify Artifacts (source-zendesk-chat), Format Check, Check Changelog Updated, Connector CI Checks Summary. Connector test results: 46 tests, 42 ✅ / 4 💤 / 0 ❌. Pre-release and rollout check-runs are excluded from this gate by design.
Live / E2E Tests	PASS	Yes	Validation is required (bug fix + API error-handling change). /ai-prove-fix posted 🟢 Fix Proven on this HEAD (comment 5178445154): a real Zendesk 401 reproduced the old CDK message on the master manifest and the new Zendesk-specific message on this PR's, with status staying FAILED/config_error, plus clean comparison regression tests against control 1.3.21. This gate maps that conclusion directly.

Changed-line evidence for the keyword gates — added/removed lines were extracted from the PR diff (context lines excluded, comment lines excluded) before matching:

• Security keyword matches: none
• Forwards-compatibility keyword matches: none
• Behavioral-change keyword matches: error_handler, response_filters, HttpResponseFilter, http_codes, backoff_strategies, Retry-After (all within manifest.yaml)

Spec comparison: not applicable — no spec*.json/spec*.yaml file and no spec section in manifest.yaml was modified.

📚 Evidence Consulted

Evidence

• Changed files: 4
  • airbyte-integrations/connectors/source-zendesk-chat/manifest.yaml (+26 / −96)
  • airbyte-integrations/connectors/source-zendesk-chat/metadata.yaml (+1 / −1)
  • airbyte-integrations/connectors/source-zendesk-chat/unit_tests/mock_server/test_routing_settings.py (+21 / −0)
  • docs/integrations/sources/zendesk-chat.md (+1 / −0)
• CI checks: all core checks success on a05ae82; no failed, cancelled, or timed-out check-runs at time of review
• PR labels: connectors/source/zendesk-chat, hyd-prove, hyd-review
• PR description: present and substantive
• Human reviews / review comments: none (0 reviews, 0 inline comments)
• Existing bot reviews for this SHA: none
• /ai-prove-fix conclusion: 🟢 Fix Proven (fix(source-zendesk-chat): name Zendesk Chat and the access token in 401 errors #83336 (comment))

❓ How to Respond

Resolving a Failing Gate

Behavioral Changes is a warning-level gate: it surfaces here and raises the Risk Level, but it does not block approval and requires no remediation from you. The keyword match is expected for a PR that intentionally edits error-handling configuration.

If you believe a gate verdict is a false positive or cannot be remediated as written, request review from a human maintainer and explain the situation in a PR comment — a human reviewer can approve or merge over a bot verdict. Written explanations in the PR description do not change a gate verdict.

---

Devin session

[Airbyte Support Bot (airbyte-support-bot)]

↪️ Triggering /ai-ready per Hands-Free AI Triage Project triage next step.

Reason: /ai-review returned APPROVE for the exact current HEAD a05ae826 on top of a 🟢 Fix Proven, CI is green, and the branch is not conflicted.

Devin session

[octavia-bot-hoard]

Auto-merge evaluation: FAIL

Preconditions (all must pass)

Status	Check	Reasoning
✅	No Breaking Changes	Message-only fix: adds a 401 HttpResponseFilter and refactors 12 identical inline DefaultErrorHandlers into a shared definitions.error_handler $ref. 404 IGNORE and Retry-After backoff preserved. No spec, schema, state, or API change; non-breaking patch bump 1.3.21 -> 1.3.22 with no breakingChanges entry or migration guide.
✅	Ai Review Passed	Comment 5179554476 by airbyte-support-bot contains '', matching the current HEAD (a05ae82). 11/12 gates PASS; Behavioral Changes is a warning-level FAIL that did not block approval.
✅	Airbyte Support Bot Assigned	Airbyte Support Bot assignment confirms automated merge eligibility.
✅	No Destination Changes	No destination-related changes detected.

Change scope (at least one must pass)

❌ No matching change scope detected.

Devin session | Workflow run

[Airbyte Support Bot (airbyte-support-bot)]

🙋 Escalated to #human-in-the-loop per Hands-Free AI Triage Project triage next step.

Reason: /ai-ready returned FAIL with every precondition passing — no breaking changes, AI review APPROVE matching the exact current HEAD, Airbyte Support Bot assigned, no destination changes. The single failure is No matching change scope detected, so the auto-merge scope classifier does not recognise this change shape. This is the fourth PR today blocked on that same check, alongside #82773, so it reads as an auto-merge scope-rule gap rather than a problem with the PR. A human needs to merge directly, or the scope rules need widening.

Devin session