languagetool-org/languagetool · error · BadRequestException

You're using an old version of our API that's not supported

Error message

You're using an old version of our API that's not supported anymore. Please see 

What it means

The LanguageTool HTTP handler rejects legacy API endpoints with a BadRequestException. Requests ending in '/Languages' (the old v1 way to list languages) are no longer supported; clients must use the versioned /v2 API instead.

Source

Thrown at languagetool-server/src/main/java/org/languagetool/server/LanguageToolHttpHandler.java:215

                " per " + errorRequestLimiter.getRequestLimitPeriodInSeconds() + " seconds";
        int code = 429; // too many requests
        sendError(httpExchange, code, errorMessage);
        logError(errorMessage, code, parameters, httpExchange);
        return;
      }
      if (workQueueFull(httpExchange, parameters, "Error: There are currently too many parallel requests. Please try again later.")) {
        ServerMetricsCollector.getInstance().logRequestError(ServerMetricsCollector.RequestErrorType.QUEUE_FULL);
        return;
      }
      if (allowedIps == null || allowedIps.contains(origAddress)) {
        if (path.startsWith("/v2/")) {
          ApiV2 apiV2 = new ApiV2(textCheckerV2, config.getAllowOriginUrl());
          String pathWithoutVersion = path.substring("/v2/".length());
          final Map<String, String> finalParameters = parameters;
          final String finalRemoteAddress = remoteAddress;
          TelemetryProvider.INSTANCE.createSpan("/v2", Attributes.empty(), () -> apiV2.handleRequest(pathWithoutVersion, httpExchange, finalParameters, errorRequestLimiter, finalRemoteAddress, config));
        } else if (path.endsWith("/Languages")) {
          throw new BadRequestException("You're using an old version of our API that's not supported anymore. Please see " + API_DOC_URL);
        } else if (path.equals("/")) {
          throw new BadRequestException("Missing arguments for LanguageTool API. Please see " + API_DOC_URL);
        } else if (path.contains("/v2/")) {
          throw new BadRequestException("You have '/v2/' in your path, but not at the root. Try an URL like 'http://server/v2/...' ");
        } else if (path.equals("/favicon.ico")) {
          sendError(httpExchange, HttpURLConnection.HTTP_NOT_FOUND, "Not found");
        } else {
          throw new BadRequestException("This is the LanguageTool API. You have not specified any parameters. Please see " + API_DOC_URL);
        }
      } else {
        String errorMessage = "Error: Access from " + StringTools.escapeXML(origAddress) + " denied";
        sendError(httpExchange, HttpURLConnection.HTTP_FORBIDDEN, errorMessage);
        throw new RuntimeException(errorMessage);
      }
    } catch (Exception e) {
      String response;
      int errorCode;
      boolean textLoggingAllowed = false;

View on GitHub (pinned to 2e990059ce)

Solutions

1. Change the client to call `GET /v2/languages` (lowercase) to list supported languages
2. Upgrade any LanguageTool client library to a version that targets the v2 API
3. Follow the API documentation URL included in the error message to map old endpoints to v2 equivalents

Example fix

// before
curl http://server:8081/Languages
// after
curl http://server:8081/v2/languages

// client-side: ensure v2 endpoint
if (!apiUrl.endsWith("/v2/languages")) {
  apiUrl = apiUrl.replaceFirst("/(Languages)$", "/v2/languages");
}

HttpResponse<String> resp = client.send(req, BodyHandlers.ofString());
if (resp.statusCode() == 400 && resp.body().contains("not supported anymore")) {
  throw new IllegalStateException("Legacy API endpoint used; migrate to /v2");
}

When it happens

Trigger: An HTTP request whose path ends with `/Languages` reaches handle() — i.e. a client calling the deprecated v1 `GET /Languages` endpoint on the server root.

Common situations: Old client code or scripts written for LanguageTool API v1 still listing languages via `/Languages`, tutorials/bookmarks predating the v2 API, or libraries that never migrated to `/v2/languages`.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• 'language' parameter missing
• Set only 'text' or 'data' parameter, not both
• Could not parse JSON from 'data' parameter
• 'data' key in JSON requires either 'text' or 'annotation' ke
• 'data' key in JSON requires 'text' or 'annotation' key

AI-assisted analysis of languagetool-org/languagetool@2e990059ce (2026-09-06). Data as JSON: /api/errors/08a54e1cc0e19470. Report an issue: GitHub.