diff --git a/src/adapters/http/client.ts b/src/adapters/http/client.ts
index 5128347f..713e3339 100644
--- a/src/adapters/http/client.ts
+++ b/src/adapters/http/client.ts
@@ -40,7 +40,7 @@ import type { ClockPort } from "../../application/ports/clock-port.ts";
import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.ts";
import type { TelemetryPort } from "../../application/ports/telemetry-port.ts";
import type { ApiOperation } from "../../contracts/api-operations.ts";
-import type { ApiFailure } from "../../contracts/errors.ts";
+import type { ApiFailure, FailureKind } from "../../contracts/errors.ts";
import type { OperationRequestInput } from "./request-builder.ts";
import { readBoundedJson } from "./bounded-json.ts";
import { admitCredentialHeaders } from "./http-contract-bridge.ts";
@@ -841,6 +841,17 @@ export function createHttpClient(
class LogicalDeadlineError extends Error {}
+/**
+ * Q-6.3-3b. A gateway 5xx/408/425 with an HTML, empty or broken body is a
+ * server outage, not a contract breach: it keeps its status and the normal
+ * SERVER_FAILURE retry rule instead of a non-retryable body error.
+ */
+function gatewayFailureOr(status: number, kind: FailureKind): FailureKind {
+ return status >= 500 || status === 408 || status === 425
+ ? "SERVER_FAILURE"
+ : kind;
+}
+
async function parseResponse(
response: Response,
operation: ApiOperation,
@@ -861,10 +872,12 @@ async function parseResponse(
void response.body?.cancel().catch(() => {});
return {
ok: false,
- error: failure("CONTENT_TYPE_MISMATCH", operation.operationId, attempt, {
- code: "CONTENT_TYPE_MISMATCH",
- httpStatus: response.status,
- }),
+ error: failure(
+ gatewayFailureOr(response.status, "CONTENT_TYPE_MISMATCH"),
+ operation.operationId,
+ attempt,
+ { code: "CONTENT_TYPE_MISMATCH", httpStatus: response.status },
+ ),
};
}
@@ -875,10 +888,12 @@ async function parseResponse(
if (!decoded.ok) {
return {
ok: false,
- error: failure(decoded.code, operation.operationId, attempt, {
- code: decoded.code,
- httpStatus: response.status,
- }),
+ error: failure(
+ gatewayFailureOr(response.status, decoded.code),
+ operation.operationId,
+ attempt,
+ { code: decoded.code, httpStatus: response.status },
+ ),
};
}
const envelope = decoded.value;
@@ -888,7 +903,9 @@ async function parseResponse(
return {
ok: false,
error: failure(
- response.ok ? "ENVELOPE_MISMATCH" : statusKind(response.status),
+ response.ok
+ ? "ENVELOPE_MISMATCH"
+ : gatewayFailureOr(response.status, statusKind(response.status)),
operation.operationId,
attempt,
{
diff --git a/tests/integration/http-client.test.ts b/tests/integration/http-client.test.ts
index 348aeb3c..2390124f 100644
--- a/tests/integration/http-client.test.ts
+++ b/tests/integration/http-client.test.ts
@@ -145,7 +145,7 @@ describe("shared HTTP client", () => {
server.use(
http.get(
"https://api.test/api/entities",
- () => new HttpResponse("raw body", { status: 502 }),
+ () => new HttpResponse("raw body", { status: 200 }),
),
);
const client = testClient({ baseUrl: "https://api.test", clock });
@@ -158,6 +158,43 @@ describe("shared HTTP client", () => {
expect(JSON.stringify(result)).not.toContain("raw body");
});
+ // Q-6.3-3b. A gateway 5xx/408/425 with an HTML, empty or broken body is a
+ // server outage, not a contract breach: it keeps its status and the V2
+ // SERVER_FAILURE retry rule (502/503/504 only).
+ it.each([
+ { status: 502, contentType: "text/html", body: "raw body", fetches: 3 },
+ { status: 503, contentType: "application/json", body: "", fetches: 3 },
+ { status: 504, contentType: "application/json", body: "{", fetches: 3 },
+ { status: 408, contentType: "text/plain", body: "timeout", fetches: 1 },
+ ])(
+ "keeps a $status gateway body as a server failure with its status",
+ async ({ status, contentType, body, fetches }) => {
+ let fetched = 0;
+ server.use(
+ http.get("https://api.test/api/entities", () => {
+ fetched += 1;
+ return new HttpResponse(body, {
+ status,
+ headers: { "Content-Type": contentType },
+ });
+ }),
+ );
+ const client = testClient({
+ baseUrl: "https://api.test",
+ clock,
+ random: () => 0,
+ });
+ const result = await client.execute("LIST_ENTITIES");
+
+ expect(result).toMatchObject({
+ ok: false,
+ error: { kind: "SERVER_FAILURE", httpStatus: status },
+ });
+ expect(fetched).toBe(fetches);
+ expect(JSON.stringify(result)).not.toContain("raw body");
+ },
+ );
+
it("classifies malformed JSON and invalid payloads at the boundary", async () => {
server.use(
http.get(