binarywang/WxJava · error · WxRuntimeException

微信服务端异常，超出重试次数

Error message

微信服务端异常，超出重试次数

What it means

Thrown inside the retry loop of BaseCpServiceImpl.execute() when a retried call fails again and retryTimes + 1 exceeds maxRetryTimes. Only the errcode == -1 (WeChat 'system busy') branch is retried; once retries run out on that branch the original WxErrorException is discarded and replaced with WxRuntimeException('微信服务端异常，超出重试次数').

Source

Thrown at weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/BaseWxCpServiceImpl.java:353

    String urlWithToken = url + (url.contains("?") ? "&" : "?") + "access_token=" + contactAccessToken;
    // 使用executeNormal方法，不自动添加token
    return this.executeNormal(SimplePostRequestExecutor.create(this), urlWithToken, postData);
  }

  /**
   * 向微信端发送请求，在这里执行的策略是当发生access_token过期时才去刷新，然后重新执行请求，而不是全局定时请求.
   */
  @Override
  public <T, E> T execute(RequestExecutor<T, E> executor, String uri, E data) throws WxErrorException {
    int retryTimes = 0;
    do {
      try {
        return this.executeInternal(executor, uri, data, false);
      } catch (WxErrorException e) {
        if (retryTimes + 1 > this.maxRetryTimes) {
          log.warn("重试达到最大次数【{}】", this.maxRetryTimes);
          //最后一次重试失败后，直接抛出异常，不再等待
          throw new WxRuntimeException("微信服务端异常，超出重试次数");
        }

        WxError error = e.getError();
        /*
         * -1 系统繁忙, 1000ms后重试
         */
        if (error.getErrorCode() == -1) {
          int sleepMillis = this.retrySleepMillis * (1 << retryTimes);
          try {
            log.debug("微信系统繁忙，{} ms 后重试(第{}次)", sleepMillis, retryTimes + 1);
            Thread.sleep(sleepMillis);
          } catch (InterruptedException e1) {
            Thread.currentThread().interrupt();
          }
        } else {
          throw e;
        }
      }

View on GitHub (pinned to 1c43293a3c)

Solutions

  1. Tune maxRetryTimes and retrySleepMillis so the backoff covers transient WeChat degradation.
  2. Catch WxRuntimeException here and surface a 'service temporarily unavailable' to the caller with retry guidance.
  3. Check WeChat platform status and your app's call volume/rate limits.
  4. Note this masks the original WxErrorException - log errcode/-1 context before the throw is lost.

Example fix

// before
result = service.execute(executor, uri, data);
// after
try {
  result = service.execute(executor, uri, data);
} catch (WxRuntimeException e) {
  if ("微信服务端异常，超出重试次数".equals(e.getMessage())) {
    throw new ServiceUnavailableException("WeChat busy, retry later", e);
  }
  throw e;
}
Defensive patterns

Strategy: retry

Validate before calling

if (service.getMaxRetryTimes() <= 0) {
  // configure retries for -1 system-busy responses
  log.warn("no retries configured; WeChat busy will surface as runtime error");
}

Type guard

null

Try / catch

try {
  result = service.execute(executor, uri, data);
} catch (WxRuntimeException e) {
  if ("微信服务端异常，超出重试次数".equals(e.getMessage())) {
    throw new ServiceUnavailableException("WeChat busy, retry later", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: WeChat returning errcode -1 (system busy) persistently across all retry attempts; maxRetryTimes configured too low for a prolonged WeChat degradation.

Common situations: WeChat-side incident causing sustained -1 responses; retrySleepMillis/maxRetryTimes misconfigured (too few retries or too short backoff); high-traffic windows hitting WeChat rate pressure.

Related errors

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