binarywang/WxJava · error · WxErrorException

错误代码：{errorCode}, 错误信息：{errorMsg}

Error message

错误代码：{errorCode}, 错误信息：{errorMsg}

What it means

Thrown by the OkHttp media-upload request executor after the WeChat server replies with a non-zero errcode. The executor builds a multipart/form-data body (a 'media' part typed application/octet-stream), runs the OkHttp call, parses response.body().string() into a WxError, and on error.getErrorCode() != 0 rethrows it as WxErrorException. It represents a WeChat API-level rejection of a media/material upload, not an HTTP transport failure.

Source

Thrown at weixin-java-common/src/main/java/me/chanjar/weixin/common/util/http/okhttp/OkHttpMediaUploadRequestExecutor.java:40

    super(requestHttp);
  }

  @Override
  public WxMediaUploadResult execute(String uri, File file, WxType wxType) throws WxErrorException, IOException {

    RequestBody body = new MultipartBody.Builder()
      .setType(MediaType.parse("multipart/form-data"))
      .addFormDataPart("media",
        file.getName(),
        RequestBody.create(MediaType.parse("application/octet-stream"), file))
      .build();
    Request request = new Request.Builder().url(uri).post(body).build();

    Response response = requestHttp.getRequestHttpClient().newCall(request).execute();
    String responseContent = response.body().string();
    WxError error = WxError.fromJson(responseContent, wxType);
    if (error.getErrorCode() != 0) {
      throw new WxErrorException(error);
    }
    return WxMediaUploadResult.fromJson(responseContent);
  }

}

View on GitHub (pinned to 1c43293a3c)

Solutions

  1. Catch WxErrorException and read e.getError().getErrorCode()/getErrorMsg() to get the exact WeChat code, then look it up in WeChat's global return-code table.
  2. Verify the access_token is fresh and the config storage auto-refresh is enabled before the upload.
  3. Check the file against WeChat limits (size, format, extension) before posting.
  4. Confirm the request executor type and URL constant match the WeChat endpoint you intend to call.

Example fix

// before
WxMediaUploadResult r = service.executeMediaUploadRequest(url, file);
// after
try {
  WxMediaUploadResult r = service.executeMediaUploadRequest(url, file);
} catch (WxErrorException e) {
  log.error("upload failed errcode={} msg={}",
    e.getError().getErrorCode(), e.getError().getErrorMsg());
  throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// validate before upload
File f = ...;
long MAX = 2L * 1024 * 1024; // example limit
if (!f.exists() || f.length() > MAX) {
  throw new IllegalArgumentException("invalid media file");
}
if (!service.getWxCpConfigStorage().isAccessTokenExpired()) {
  // token looks fresh
}

Type guard

null

Try / catch

try {
  WxMediaUploadResult r = executor.execute(uri, file, wxType);
} catch (WxErrorException e) {
  WxError err = e.getError();
  log.error("media upload errcode={} msg={}", err.getErrorCode(), err.getErrorMsg());
  // token errors -> refresh & retry once; others -> propagate
  throw e;
}

Prevention

When it happens

Trigger: Calling any media-upload endpoint that uses OkHttpMediaUploadRequestExecutor (temporary/permanent material upload) when the access_token is invalid/expired, the file exceeds WeChat size limits, the media format/extension is unsupported, or the response body is not valid JSON (e.g. an HTML gateway error page that yields a parsed errorCode other than 0).

Common situations: Expired access_token used after long idle; image larger than the documented limit; missing/incorrect file extension; corporate proxy returning HTML on overload; wrong wxType passed so the error code translation misfires.

Related errors

AI-assisted analysis of binarywang/WxJava@1c43293a3c (2026-08-14). Data as JSON: /api/errors/07f29765116d7aa5. Report an issue: GitHub.