# Retry and Ambiguity The platform never decides a retry from the HTTP method alone (design D-09). A second attempt happens only when idempotency, body replayability, execution evidence, deadline, and retry budget all permit it. ## Execution evidence | Evidence | Meaning | Typical cause | |---|---|---| | `NOT_SENT` | Proven that the server never received the request | profile rejection, pool timeout, DNS failure, connect failure, pre-request TLS failure, HTTP/2 `REFUSED_STREAM` | | `SENT_NO_RESPONSE` | Some or all of the request was written, no final header arrived | partial write, response-header timeout, connection reset | | `RESPONSE_RECEIVED` | Final headers arrived, whatever the status | 2xx, 4xx, 5xx, redirect | | `PARTIAL_RESPONSE` | Headers and part of the body arrived | reset during decode, interrupted stream | `NOT_SENT` is only produced by a stage failure that proves it. A generic engine I/O error is never upgraded to `NOT_SENT`, because that is exactly how a timeout becomes a duplicate payment. ## Body replayability | Body | Replayability | |---|---| | immutable `byte[]` | `REPLAYABLE` | | DTO plus a deterministic codec | `REPLAYABLE` | | reopenable file or resource supplier | `REOPENABLE` | | a single `InputStream` instance | `ONE_SHOT` | | publisher factory | as declared | | publisher instance | `ONE_SHOT` | | multipart | the weakest part | ## Decision order `DefaultRetryEligibilityEngine` evaluates in this order, and a later rule can never re-enable something an earlier one forbade: 1. `SENT_NO_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure` 2. attempts exhausted → `RetryDenied.maxAttempts()` 3. retry budget empty → `RetryDenied.budgetExhausted()` 4. body not replayable → `RetryDenied.bodyNotReplayable()` 5. first byte already delivered → `RetryDenied.responseAlreadyDelivered()` 6. runtime draining → `RetryDenied.runtimeDraining()` 7. remaining deadline below the minimum attempt budget → `RetryDenied.deadline()` 8. permanent failure category → `RetryDenied.permanentFailure(...)` 9. `PARTIAL_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure` 10. status- and failure-specific rules Ambiguity comes first because it describes the outcome, not whether another attempt is allowed. It used to sit below the attempt check, so with the default `max-attempts: 1` a POST that timed out after it was sent reached the caller as an ordinary timeout (review 2026-11-01 05-14). ## Status rules | Status | Decision | |---|---| | 408 | retry inside deadline and budget | | 425 | at most one retry, first attempt only | | 429 | retry inside `Retry-After`, deadline, and budget | | 401 | one refresh-and-replay, safe replayable operations only. The credential is refreshed only once the retry is granted; a 401 that will not be replayed (one attempt, no budget, no deadline) leaves the token cache alone | | 500 | denied unless the upstream registered it as transient **and** the operation is safely idempotent | | 502, 503, 504 | retry for safely idempotent operations; ambiguous otherwise | | other 4xx | denied | ## Ambiguity A non-idempotent request that reached `SENT_NO_RESPONSE` raises `HttpAmbiguousExecutionException`. It is a third answer on purpose: retrying may duplicate a side effect, and reporting a plain failure would tell the caller the request did not happen, which may be false. The caller reconciles, usually by querying the upstream or replaying with an idempotency key. ### Where the evidence comes from Whether a failed request was sent is read from the stage the attempt reached and the engine's exception type. Apache reports the moment it starts writing the request onto an established connection (`RequestWriteSignal`), so a failure while leasing, resolving, connecting or completing the TLS handshake is `NOT_SENT` even when the engine throws a generic exception. Transports that cannot report that moment (JDK, Jetty) are treated as writing from the moment the engine is called, because guessing "not sent" is what turns a timeout into a duplicate payment. An HTTP/2 `REFUSED_STREAM` frame is proof the peer processed nothing and is kept as `NOT_SENT` through exception mapping. ## Budget and backoff Retry tokens come from a per-upstream token bucket sized as a fraction of real traffic, so a failing upstream cannot be flooded by retries from a healthy fleet. Backoff is exponential with full or decorrelated jitter, bounded by `max-backoff`, by `Retry-After`, and by the remaining deadline. No connection and no bulkhead permit is held while a backoff is waiting.