justauth/JustAuth · error · AuthException

${errcode}

${errcode}

Error message

${errmsg}

What it means

AuthWeChatMpRequest.checkResponse is the guard for WeChat Official Account (公众号) mini-program-style token endpoints: if the JSON contains `errcode`, it throws AuthException(int code, String msg) where the exception's numeric code is WeChat's own errcode and the message is errmsg. So unlike source-tagged exceptions, this one surfaces the raw WeChat error code (e.g. 40029, 40164, 45011).

Source

Thrown at src/main/java/me/zhyd/oauth/request/AuthWeChatMpRequest.java:96

            .build();
    }

    @Override
    public AuthResponse<AuthToken> refresh(AuthToken oldToken) {
        return AuthResponse.<AuthToken>builder()
            .code(AuthResponseStatus.SUCCESS.getCode())
            .data(this.getToken(refreshTokenUrl(oldToken.getRefreshToken())))
            .build();
    }

    /**
     * 检查响应内容是否正确
     *
     * @param object 请求响应内容
     */
    private void checkResponse(JSONObject object) {
        if (object.containsKey("errcode")) {
            throw new AuthException(object.getIntValue("errcode"), object.getString("errmsg"));
        }
    }

    /**
     * 获取token，适用于获取access_token和刷新token
     *
     * @param accessTokenUrl 实际请求token的地址
     * @return token对象
     */
    private AuthToken getToken(String accessTokenUrl) {
        String response = new HttpUtils(config.getHttpConfig()).get(accessTokenUrl).getBody();
        JSONObject accessTokenObject = JSONObject.parseObject(response);

        this.checkResponse(accessTokenObject);

        return AuthToken.builder()
            .accessToken(accessTokenObject.getString("access_token"))
            .refreshToken(accessTokenObject.getString("refresh_token"))

View on GitHub (pinned to 694bbf1b01)

Solutions

  1. Map the exception's code via WeChat's global error-code table: 40164 → add the server's egress IP to IP whitelist in the MP console; 40125 → fix appsecret; 40029 → js_code invalid/reused; 45011 → rate limited, back off.
  2. Verify AuthConfig.clientId=appId and clientSecret=appSecret belong to the same Official Account.
  3. Cache the fetched access_token (it is valid ~2h) instead of re-requesting per call to avoid 45011.
  4. Log e.getCode() numerically in your monitoring and alert on 40164 specifically after infra/IP changes.
Defensive patterns

Strategy: retry

Validate before calling

// verify the egress IP is likely whitelisted before first deploy
String ip = new HttpUtils(null).get("https://httpbin.org/ip").getBody();
log.info("egress IP to whitelist in WeChat MP console: {}", ip);
Assert.hasText(config.getClientId(), "appId required");
Assert.hasText(config.getClientSecret(), "appSecret required");

Try / catch

try {
    return mpRequest.getAccessToken(callback);
} catch (AuthException e) {
    switch (e.getCode()) {
        case 40164: throw new ConfigurationException("whitelist server IP in WeChat MP console", e);
        case 45011: backoffAndRetryOnce(); break; // rate limited
        case 40029: throw new InvalidGrantException("js_code reused/expired", e);
        default: throw e;
    }
}

Prevention

When it happens

Trigger: jscode2session-style token fetch or refresh in the WeChat MP flow failing: invalid js_code (40029), invalid appsecret (40125), IP not in whitelist (40164), api daily quota (45011), or invalid grant_type on refresh (40029/41008).

Common situations: Server IP not added to the official account's IP whitelist (40164 is extremely common on first deploy); appid/appsecret from a different account or reset after regeneration; authorization code (js_code) used twice or expired; hitting WeChat API rate limits during load tests.

Related errors

AI-assisted analysis of justauth/JustAuth@694bbf1b01 (2026-08-14). Data as JSON: /api/errors/290445afc96f2aa7. Report an issue: GitHub.