eclipse-vertx/vert.x · error

422 Unprocessable Entity (WebDAV, RFC4918)

Error message

422 Unprocessable Entity (WebDAV, RFC4918)

What it means

SC_UNPROCESSABLE_ENTITY is an HttpResponseExpectation constant for HTTP 422 (WebDAV, RFC4918). It signals a request was well-formed but semantically invalid, so the server refuses to process it. Vert.x exposes it so applications can assert or react to this status in HttpClient expectations.

Source

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

  /**
   * 416 Requested Range Not Satisfiable
   */
  HttpResponseExpectation SC_REQUESTED_RANGE_NOT_SATISFIABLE = status(416);

  /**
   * 417 Expectation Failed
   */
  HttpResponseExpectation SC_EXPECTATION_FAILED = status(417);

  /**
   * 421 Misdirected Request
   */
  HttpResponseExpectation SC_MISDIRECTED_REQUEST = status(421);

  /**
   * 422 Unprocessable Entity (WebDAV, RFC4918)
   */
  HttpResponseExpectation SC_UNPROCESSABLE_ENTITY = status(422);

  /**
   * 423 Locked (WebDAV, RFC4918)
   */
  HttpResponseExpectation SC_LOCKED = status(423);

  /**
   * 424 Failed Dependency (WebDAV, RFC4918)
   */
  HttpResponseExpectation SC_FAILED_DEPENDENCY = status(424);

  /**
   * 425 Unordered Collection (WebDAV, RFC3648)
   */
  HttpResponseExpectation SC_UNORDERED_COLLECTION = status(425);

  /**
   * 426 Upgrade Required (RFC2817)

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Read the response body (usually contains validation error details) and fix the fields that failed server-side validation.
2. Validate the payload client-side before sending (schema/bean validation) to catch problems early.
3. Check API documentation or changelog for newly required fields after a server version upgrade.
4. If 421/422 are expected outcomes, model them explicitly with the corresponding expectation instead of expecting SC_OK.

Example fix

// before
client.post(8080, "localhost", "/users").sendJsonObject(invalidBody)
  .expecting(HttpResponseExpectation.SC_CREATED);
// after
// validate body first
if (body.getString("email") == null) { throw new IllegalArgumentException("email required"); }
client.post(8080, "localhost", "/users").sendJsonObject(body)
  .expecting(HttpResponseExpectation.SC_CREATED);

Set<String> missing = requiredFields.stream().filter(f -> body.getValue(f) == null).collect(Collectors.toSet());
if (!missing.isEmpty()) throw new IllegalArgumentException("missing fields: " + missing);

boolean is422(HttpClientResponse resp) { return resp.statusCode() == 422; }

send()
  .expecting(HttpResponseExpectation.SC_CREATED)
  .onFailure(err -> { if (isCauseStatus(err, 422)) readErrorDetailsAndFixPayload(); });

When it happens

Trigger: Sending a syntactically valid request whose body/fields fail server-side business validation, e.g. POST/PUT with invalid domain data to a REST API, or WebDAV operations violating semantic constraints. Observed when chaining .expecting(HttpResponseExpectation.SC_UNPROCESSABLE_ENTITY) or when an api expects success but the server replies 422.

Common situations: REST API request bodies failing server-side validation (missing/invalid fields, constraint violations); Rails-style APIs returning 422 for model validation failures; version changes where a server started enforcing new field constraints.

Related errors

• keepAliveTimeout must be >= 0
• maxPoolSize must be > 0
• http2MaxPoolSize must be > 0
• http3MaxPoolSize must be > 0
• maxLifetime must be >= 0

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