[Jackson Smith (jackson-asmith)]

Fixes #896

This ports microsoft/kiota-dotnet#864 to Python. The Go port is microsoft/kiota-http-go#312.

Problem

RetryHandler retries 429, 503 and 504 responses whatever the HTTP method. For POST and PATCH, a retry after a 504 can apply the request twice. A 504 means a gateway stopped waiting, not that the server did nothing, so the first attempt may already have succeeded. With Microsoft Graph's sendMail, this sends the same email twice.

Callers can't avoid this today without turning off retries entirely. RetryHandlerOption.should_retry is a boolean, not a callback, so there's no way to skip retries for some methods short of subclassing the handler.

Change

This adds RetryHandlerOption.retry_unprocessed_mutations_only, matching the .NET option.

• Default is False. Existing behavior doesn't change.
• When True, POST and PATCH are retried only after a 429 or 503. By common service convention, those responses mean the server didn't process the request. A 504 is returned to the caller.
• Other methods aren't affected. GET, PUT, DELETE and QUERY keep retrying as before.
• The check runs on every attempt, so a POST that gets a 503 and then a 504 stops at the 504.
• It works as a client-wide option or per request.

options = RetryHandlerOption(retry_unprocessed_mutations_only=True)

The default pipeline runs RedirectHandler before RetryHandler, so the retry handler only sees the request for the current redirect hop and resends exactly that. Checking request.method is therefore always the method being resent. The .NET and Go versions had to account for redirects; this one doesn't.

Tests

test_retry_handler.py has 18 new cases covering:

• the default
• each method and status combination above
• method matching that ignores case
• the 503 then 504 sequence
• the per-request option
• RedirectHandler and RetryHandler together: a POST that a 303 turns into a GET is retried after a 504, and a POST kept by a 307 is not

With the new check removed from should_retry, the 6 tests for the new behavior fail and the other 12 pass. A fixture skips the wait between retries, so the new tests take about 0.1 seconds. For the httpx package, yapf, mypy, pylint and the full test suite (227 tests) pass locally on Python 3.15.

[Copilot]

🟡 Changes recommended

The tests lack RedirectHandler–RetryHandler integration coverage to verify that retry restrictions behave correctly across both method-changing and method-preserving redirects.

1 open issue

• Add retry coverage for redirect chains · New

What changed in this PR

Adds opt-in retry safety to the HTTPX middleware to reduce duplicate POST/PATCH side effects after gateway timeouts, while preserving existing behavior by default.

Changes:

• Adds retry_unprocessed_mutations_only, defaulting to False, with documentation of its safety assumptions.
• When enabled, restricts POST/PATCH retries to 429 and 503 responses without changing other methods or existing retry safeguards.
• Adds regression tests for defaults, method/status combinations, later retry attempts, and per-request configuration.

File	Description
packages/​http/​httpx/​tests/​middleware_tests/​test_retry_handler.py	Adds retry-policy regression tests and a fixture that skips retry delays.
packages/​http/​httpx/​kiota_http/​middleware/​retry_handler.py	Applies the method-specific restriction on each retry decision.
packages/​http/​httpx/​kiota_http/​middleware/​options/​retry_handler_option.py	Defines and documents the new opt-in setting.

_{Review effort: Balanced}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

🟢 Approval recommended

No active review issues block the opt-in retry protection change.

1 open issue

• Add retry coverage for redirect chains

_{Review effort: Balanced}