eclipse-vertx/vert.x · warning

408 Request Timeout

Error message

408 Request Timeout

What it means

SC_REQUEST_TIMEOUT is a constant for HTTP 408 Request Timeout. In Vert.x, HttpResponseExpectation constants are used with HttpClientResponse/expectation validation (e.g. via `expecting()` or `Validation` helpers); when a response with status 408 is received, the expectation fails and a VertxHttpResponseException carrying '408 Request Timeout' surfaces to the caller. 408 means the server closed or rejected the request because the client did not produce a request (or complete body) within its allowed time window.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java:190

  /**
   * 405 Method Not Allowed
   */
  HttpResponseExpectation SC_METHOD_NOT_ALLOWED = status(405);

  /**
   * 406 Not Acceptable
   */
  HttpResponseExpectation SC_NOT_ACCEPTABLE = status(406);

  /**
   * 407 Proxy Authentication Required
   */
  HttpResponseExpectation SC_PROXY_AUTHENTICATION_REQUIRED = status(407);

  /**
   * 408 Request Timeout
   */
  HttpResponseExpectation SC_REQUEST_TIMEOUT = status(408);

  /**
   * 409 Conflict
   */
  HttpResponseExpectation SC_CONFLICT = status(409);

  /**
   * 410 Gone
   */
  HttpResponseExpectation SC_GONE = status(410);

  /**
   * 411 Length Required
   */
  HttpResponseExpectation SC_LENGTH_REQUIRED = status(411);

  /**
   * 412 Precondition Failed

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Retry the request on a fresh connection instead of a pooled idle one (the server may have dropped the keep-alive connection)
2. Reduce time between connection/open and sending the full request; write headers and body promptly
3. Increase the server/proxy client-header/body timeout if you legitimately send large or slow bodies
4. Check that any request body pump (e.g. file/stream upload) is not stalled; add progress/timeout logging
5. Enable client keep-alive timeout shorter than the server's so stale connections are proactively closed

Example fix

// before
request.send() // reuses idle pooled connection, gets 408
// after
client.request(requestOptions)
  .onSuccess(req -> req.response()
      .expecting(HttpResponseExpectation.SC_REQUEST_TIMEOUT.negate())
      .onSuccess(resp -> { /* handle */ })
      .end()); // fresh request, failed expectation handled explicitly

// Ensure request is sent promptly after creation
if (!request.isComplete() /* pending body */) { /* pump body immediately or abort */ }
// Optionally close stale pooled connections proactively:
client.connectionHandler(conn -> conn.exceptionHandler(err -> log.warn("conn reset", err)));

boolean isRequestTimeout(Throwable t) {
  return t instanceof VertxHttpResponseException
    && ((VertxHttpResponseException) t).getResponse().statusCode() == 408;
}

if (isRequestTimeout(t)) { retryOnceOnFreshConnection(req); } else { fail(t); }

When it happens

Trigger: Calling an HTTP endpoint via Vert.x HttpClient/ WebClient while using status expectations, and the remote server returns 408 because the request headers/body were sent too slowly or the connection idled before the request completed.

Common situations: Slow request body uploads over poor networks, client code that opens a connection and delays writing the request, intermediaries (proxies/load balancers) with short idle timeouts, retry logic that reuses an idle keep-alive connection the server already timed out.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Result is already complete
• Multipart form requires multipart/form-data content type ins
• Sending form requires multipart/form-data or " + HttpHeaders
• only '\n' is allowed after '\r': <seq>
• only ' ' and '\t' are allowed after '\n': <seq>

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/d76472a7af475822. Report an issue: GitHub.