fix(http): fail fast on HTTP 413 instead of retrying

[devin-ai-integration]

Summary

HTTP 413 was missing from DEFAULT_ERROR_MAPPING, so a 413 fell through DefaultHttpResponseFilter into create_fallback_error_resolution(), which returns RETRY + system_error and a raw dump of the response body as the user-facing message:

Response was not ok: `413 Client Error: Request Entity Too Large for url: https://.../v1/notes/not_XXX?include=transcript`. Response content is: {"code":"TRANSCRIPT_TOO_LARGE", ...,"requestId":"8996...","timestamp":"..."}

A 413 is deterministic for a given request — it cannot succeed on retry — so the connector burned its whole retry budget before failing, and the message it surfaced was a non-deterministic string containing the request URL, the vendor payload, and a requestId.

+    413: ErrorResolution(
+        response_action=ResponseAction.FAIL,
+        failure_type=FailureType.system_error,
+        error_message="HTTP Status Code: 413. Error: The request or its response exceeds the size limit accepted by the API.",
+    ),

system_error rather than config_error: nothing in the user's source configuration causes or fixes an oversized request/response, so there is no remediation to offer the user (per the error-message guidelines, remediation hints belong only on config_error). The behavioral fix that matters here is FAIL instead of RETRY. Connectors that have a stream-specific remedy (e.g. fetching an oversized transcript from a paginated endpoint) should still override this with their own HttpResponseFilter.

Resolves https://github.com/airbytehq/airbyte-internal-issues/issues/16937
Related to https://github.com/airbytehq/airbyte-internal-issues/issues/16925 (the source-granola connector-side fix)

Verified with poetry run pytest unit_tests/sources/declarative/requesters/error_handlers unit_tests/sources/streams/http -q (559 passed), plus ruff check/format and mypy.

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

[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/1786498463-http-413-error-mapping#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/1786498463-http-413-error-mapping

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 231 tests  +2   4 219 ✅ +2   8m 30s ⏱️ +6s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 4e5d5fa. ± Comparison against base commit 68bc294.

This pull request removes 1 and adds 3 tests. Note that renamed tests count towards both.

unit_tests.sources.declarative.requesters.error_handlers.test_default_error_handler ‑ test_default_error_handler_with_default_response_filter[_with_unmapped_http_status_418-418-expected_error_resolution4]

unit_tests.sources.declarative.requesters.error_handlers.test_default_error_handler ‑ test_default_error_handler_with_default_response_filter[_with_http_response_status_413-413-expected_error_resolution4]
unit_tests.sources.declarative.requesters.error_handlers.test_default_error_handler ‑ test_default_error_handler_with_default_response_filter[_with_unmapped_http_status_418-418-expected_error_resolution5]
unit_tests.sources.declarative.requesters.error_handlers.test_default_http_response_filter ‑ test_matches_mapped_http_status_code[413 mapping]

[github-actions]

PyTest Results (Full)

4 234 tests  +2   4 222 ✅ +2   12m 37s ⏱️ -10s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 4e5d5fa. ± Comparison against base commit 68bc294.

This pull request removes 1 and adds 3 tests. Note that renamed tests count towards both.

unit_tests.sources.declarative.requesters.error_handlers.test_default_error_handler ‑ test_default_error_handler_with_default_response_filter[_with_unmapped_http_status_418-418-expected_error_resolution4]

unit_tests.sources.declarative.requesters.error_handlers.test_default_error_handler ‑ test_default_error_handler_with_default_response_filter[_with_http_response_status_413-413-expected_error_resolution4]
unit_tests.sources.declarative.requesters.error_handlers.test_default_error_handler ‑ test_default_error_handler_with_default_response_filter[_with_unmapped_http_status_418-418-expected_error_resolution5]
unit_tests.sources.declarative.requesters.error_handlers.test_default_http_response_filter ‑ test_matches_mapped_http_status_code[413 mapping]