What causes "503 Service Unavailable" in eclipse-vertx/vert.x?

Retry later with backoff (respect Retry-After if present)

503 Service Unavailable

Error message

503 Service Unavailable

What it means

Constant defining the 503 Service Unavailable response expectation: applying expecting(SC_SERVICE_UNAVAILABLE) turns a 503 response into a failed request future. The server is overloaded or down for maintenance; the 'message' is the reason attached to the failure.

Source

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

  /**
   * 500 Internal Server Error
   */
  HttpResponseExpectation SC_INTERNAL_SERVER_ERROR = status(500);

  /**
   * 501 Not Implemented
   */
  HttpResponseExpectation SC_NOT_IMPLEMENTED = status(501);

  /**
   * 502 Bad Gateway
   */
  HttpResponseExpectation SC_BAD_GATEWAY = status(502);

  /**
   * 503 Service Unavailable
   */
  HttpResponseExpectation SC_SERVICE_UNAVAILABLE = status(503);

  /**
   * 504 Gateway Timeout
   */
  HttpResponseExpectation SC_GATEWAY_TIMEOUT = status(504);

  /**
   * 505 HTTP Version Not Supported
   */
  HttpResponseExpectation SC_HTTP_VERSION_NOT_SUPPORTED = status(505);

  /**
   * 506 Variant Also Negotiates (RFC2295)
   */
  HttpResponseExpectation SC_VARIANT_ALSO_NEGOTIATES = status(506);

  /**
   * 507 Insufficient Storage (WebDAV, RFC4918)

View on GitHub (pinned to fb308bd8c3)

Solutions

Retry later with backoff (respect Retry-After if present)
Use a fallback endpoint when the service is unavailable

Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java:305 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

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