fix(cdk): Surface HTTP cache operational errors

[devin-ai-integration]

Summary

• Wrap SQLite OperationalError failures from the cached HTTP session with a deterministic AirbyteTracedException message: Internal HTTP response cache failed.
• Preserve the raw SQLite details in internal_message and classify the failure as system_error.
• Make the concurrent-read aggregate exception preserve config-only and transient-only classifications, while treating mixed or unclassified failures as system_error.
• Resolves https://github.com/airbytehq/airbyte-internal-issues/issues/16370
• Related to https://github.com/airbytehq/oncall/issues/12450

Review & Testing Checklist for Human

• Confirm the OperationalError wrapper is scoped narrowly enough to requests-cache SQLite failures surfaced through the HTTP session.
• Confirm the aggregate concurrent-read FailureType fallback behavior matches platform retry expectations for mixed failure sets.
• If practical, validate with a connector that uses use_cache: true under concurrent reads.

Notes

• Breaking-change evaluation: not breaking. This changes a CDK error message and reclassifies the affected aggregate cache failure away from config_error only when underlying failures are not config-only.
• Local checks:
  • poetry run ruff check .
  • poetry run mypy airbyte_cdk
  • poetry run pytest unit_tests/sources/streams/http/test_http_client.py unit_tests/sources/streams/concurrent/test_concurrent_read_processor.py -q

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

[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 and CI 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/1778321821-gitlab-cache-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/1778321821-gitlab-cache-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 045 tests  +2   4 034 ✅ +2   7m 44s ⏱️ -4s
    1 suites ±0      11 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 23f76d3. ± Comparison against base commit ccc185f.

[github-actions]

PyTest Results (Full)

4 048 tests  +2   4 036 ✅ +2   11m 4s ⏱️ +3s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 23f76d3. ± Comparison against base commit ccc185f.

[devin-ai-integration]

Runtime test results

Tested the Python CDK library changes locally with shell-only runtime assertions; no browser recording was needed.

Escalation / limitation: I did not run a live GitLab sync. I directly exercised the CDK runtime paths changed by the PR by forcing the exception states that would otherwise require a flaky requests-cache SQLite concurrency failure.

• Passed: HTTP cache sqlite3.OperationalError("no more rows available") raises AirbyteTracedException with exact message Internal HTTP response cache failed., exact internal message HTTP response cache operation failed with OperationalError: no more rows available, and FailureType.system_error.
• Passed: Concurrent-read aggregate failure with a collected cache/system error raises AirbyteTracedException with FailureType.system_error, not FailureType.config_error.
• Passed: Generic non-traced ValueError handling still emits exact message An unexpected error occurred in stream stream: ValueError, does not expose the raw exception detail in the user-facing message, and remains FailureType.system_error.
• Passed: poetry run ruff check . exited 0 with All checks passed!.
• Passed: poetry run mypy airbyte_cdk exited 0 with Success: no issues found in 454 source files.
• Passed: PR CI reported 28 passed, 0 failed, 0 pending, 1 skipped.

Commands

poetry run pytest \
  unit_tests/sources/streams/http/test_http_client.py::test_session_operational_error_raises_cache_traced_exception \
  unit_tests/sources/streams/concurrent/test_concurrent_read_processor.py::TestConcurrentReadProcessor::test_is_done_uses_failure_type_from_collected_exceptions \
  unit_tests/sources/streams/concurrent/test_concurrent_read_processor.py::TestConcurrentReadProcessor::test_on_exception_non_ate_uses_templated_message_with_correct_failure_type \
  -q

3 passed, 3 warnings in 0.27s

poetry run ruff check .
All checks passed!

poetry run mypy airbyte_cdk
Success: no issues found in 454 source files

---

Devin session

[devin-ai-integration]

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

Reason: CDK PR is linked to a connector oncall issue, CI is passing, and no AI review marker is present.

Devin session