Why should a REST Assured polling loop not use then().statusCode(200) as its loop condition?

## How a REST Assured expectation fails `then()` does not return a verdict. It returns a `ValidatableResponse` you can chain more expectations onto, and the expectations themselves are accumulated and checked. When any of them fails, REST Assured's internal response specification assembles a message — how many expectations failed, what each one expected, what it got, plus anything you supplied through `onFailMessage(...)` — and throws an `AssertionError` carrying it. That single design decision is why a validating call cannot be a loop condition. There is no boolean overload and no result object to inspect. The only way to keep going after a failure is to catch the throwable. ## What the catch actually swallows Write the tempting loop against a tram fare-inspection and you get this: ```java boolean settled = false; while (!settled && System.currentTimeMillis() < deadline) { try { given().spec(fares).pathParam("inspectionId", inspectionId) .when().get("/inspections/{inspectionId}") .then().statusCode(200) .body("status", equalTo("SETTLED")); settled = true; } catch (AssertionError notYet) { Thread.sleep(500L); } } ``` Every one of the following throws the same `AssertionError` and lands in the same catch: - the inspection is genuinely still `PENDING` — the one case you meant to handle; - the endpoint answered `500` because the fare engine fell over; - the endpoint answered `404` because the `inspectionId` was never persisted; - the field was renamed from `status` to `settlementStatus`, so the path resolves to nothing; - the response is now `text/html` from a proxy error page rather than JSON; - your matcher was wrong all along and would never have passed. The loop treats all six as "not ready yet", waits out the deadline, and then fails with whatever your timeout code says. The report names the clock. The defect is invisible. ## The shape that survives review Invert which half of the call lives inside the loop. 1. **Inside the loop, validate only invariants.** On a status resource, `then().statusCode(200)` is true whether the inspection is `PENDING` or `SETTLED`, so keeping it inside is not just harmless — it is valuable, because a real `500` now blows up immediately instead of being read as patience. 2. **Inside the loop, read rather than assert.** `extract().path("status")` returns the value as an ordinary Java object. Compare it in the `while` condition. Nothing in that comparison can throw. 3. **Outside the loop, assert once.** A final `then().body("status", equalTo("SETTLED"))` produces the real failure message — the path, the matcher and the actual value — and that is what the report carries. The difference in a red build is stark: | Loop shape | Failure message when the endpoint 500s | |---|---| | Expectation inside, `AssertionError` caught | "timed out after 20s waiting for SETTLED" | | Invariant inside, expectation outside | "expected status code 200 but was 500" | ## The narrower judgement call There is one legitimate catch, and it is not `AssertionError`. If the resource does not exist yet at all — the tram inspection has been accepted but `GET /inspections/{inspectionId}` still answers `404` for a moment — then a `404` genuinely is a not-ready signal for this API, and you should express that as data rather than as a caught throwable: - extract the status code with `extract().statusCode()` and branch on it in plain Java; - or use `then().statusCode(anyOf(is(200), is(404)))` inside the loop so both are invariants, and then read the body only when the code was 200. Both keep the "not ready" case explicit and leave every other failure free to escape immediately. Neither requires you to catch anything. ## Why this bites harder than it looks Suites that poll this way tend to look healthy for a long time, because a catch-and-continue loop converts intermittent server errors into slow passes whenever the next attempt succeeds. What you lose is the evidence: nobody ever sees the `500` that happened on attempt three, so nobody investigates it. The failure surfaces months later as "this test is slow and flaky" rather than as "the fare engine returns 500 about one call in forty". The rule worth enforcing in review is short: **no wait helper catches `AssertionError`.** If a helper needs to tolerate a condition, it tolerates it as an explicit value it read, not as an exception type that covers everything the library can complain about.