square/okhttp · error · IOException

Unexpected code

Error message

Unexpected code 

What it means

Recipe-level guard after POSTing a URL-encoded form (search=Jurassic Park) to Wikipedia's index endpoint. If the response is non-2xx, java.io.IOException("Unexpected code " + response) is thrown. Wikipedia's Special:Search via /w/index.php typically returns 200 with HTML even for no results, so reaching this guard usually means the endpoint shape changed or the request was blocked.

Source

Thrown at samples/guide/src/main/java/okhttp3/recipes/PostForm.java:38

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public final class PostForm {
  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    RequestBody formBody = new FormBody.Builder()
        .add("search", "Jurassic Park")
        .build();
    Request request = new Request.Builder()
        .url("https://en.wikipedia.org/w/index.php")
        .post(formBody)
        .build();

    try (Response response = client.newCall(request).execute()) {
      if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

      System.out.println(response.body().string());
    }
  }

  public static void main(String... args) throws Exception {
    new PostForm().run();
  }
}

View on GitHub (pinned to 4fc0831380)

Solutions

1. Add a descriptive User-Agent header per Wikimedia policy (e.g. 'MyBot/1.0 (contact@example.com)').
2. If you only need to search, use GET with ?title=Special:Search&search=... or the Action API (/w/api.php) instead of POSTing the form.
3. Inspect response.code() and the response body (often HTML with an explanatory error).

Example fix

// before
Request request = new Request.Builder()
    .url("https://en.wikipedia.org/w/index.php")
    .post(formBody)
    .build();
try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  ...
}

// after
Request request = new Request.Builder()
    .url("https://en.wikipedia.org/w/index.php")
    .header("User-Agent", "MyBot/1.0 (contact@example.com)")
    .post(formBody)
    .build();
try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) {
    throw new IOException("Wikipedia returned " + response.code()
        + ": " + response.body().string().substring(0, 200));
  }
  ...
}

// Wikimedia requires a descriptive User-Agent; add one and prefer the Action API
Request request = new Request.Builder()
    .url("https://en.wikipedia.org/w/api.php?action=query&list=search&srsearch=Jurassic+Park&format=json")
    .header("User-Agent", "MyBot/1.0 (contact@example.com)")
    .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) {
    if (response.code() == 403) throw new BlockedException("Likely User-Agent policy block");
    if (response.code() == 405) throw new MethodNotAllowedException("Use GET /w/api.php instead of POST /w/index.php");
    throw new HttpException(response.code(), response.message());
  }
}

When it happens

Trigger: POST https://en.wikipedia.org/w/index.php with form body. Fires on 405 (Wikipedia may reject POST to that path for search — search is normally GET), 415, or 403 when Wikipedia/Apache blocks the request (e.g. missing/blank User-Agent, looks like a bot).

Common situations: Wikipedia enforces a strict User-Agent policy and rejects empty/default UAs with 403; copying the recipe without adding a descriptive User-Agent; expecting JSON but Wikipedia returns HTML.

Related errors

• Unexpected code
• Unexpected code
• Unexpected code
• Unexpected code
• Unexpected code

AI-assisted analysis of square/okhttp@4fc0831380 (2026-08-04). Data as JSON: /data/errors/0b581834c41319d2.json. Report an issue: GitHub.