iflytek/astron-agent · error · AesException

-40001

-40001

Error message

Signature validation error

What it means

WXBizMsgCrypt.verifyUrl computes the SHA-1 signature over (token, timestamp, nonce, echoStr) during WeChat server URL verification and compares it to the msgSignature sent by WeChat. When the two differ it throws AesException with code -40001 (ValidateSignatureError), meaning the callback request cannot be attributed to a sender holding the correct EncodingAESKey/token pair. This is the standard WeChat callback security check failing.

Solutions

  1. Verify the token value used to construct WXBizMsgCrypt exactly matches the Token set in the WeChat MP admin console (whitespace/case included).
  2. Confirm the controller passes the original msg_signature, timestamp, nonce and echostr query parameters verbatim to verifyUrl — check URL-decoding and any reverse-proxy rewrite rules.
  3. Log the locally computed signature vs the incoming msgSignature to identify which input diverges.
  4. Ensure you are responding to WeChat's GET verification (echostr) and not a POST message push with this code path.

Example fix

// before
String sig = getSHA1(myToken, ts, nonce, echoStr); // myToken differs from MP console
// after
String sig = getSHA1(tokenFromConfigMatchingWechatConsole, ts, nonce, echoStr);
Defensive patterns

Strategy: try-catch

Validate before calling

if (msgSignature == null || timeStamp == null || nonce == null || echoStr == null) throw new IllegalArgumentException("missing WeChat verification params");

Try / catch

try { return crypto.verifyUrl(msgSignature, timestamp, nonce, echoStr); } catch (AesException e) { if (e.getCode() == -40001) { log.warn("signature mismatch"); return ResponseEntity.status(403).body("signature invalid"); } throw e; }

Prevention

When it happens

Trigger: Calling verifyUrl(msgSignature, timeStamp, nonce, echoStr) when the computed SHA1(token, timeStamp, nonce, echoStr) does not equal the msgSignature query parameter WeChat appended to the verification URL.

Common situations: Token in application config differs from the token configured in the WeChat Official Account backend; the timestamp/nonce/echoStr query params were not passed through unchanged (URL decoding issues, reordered params, proxied requests stripping query strings); a replayed or forged callback request; testing the endpoint manually without WeChat's signature params.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/8d8aca577b300446. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/hub/src/main/java/com/iflytek/astron/console/hub/util/wechat/WXBizMsgCrypt.java:209

    }

    /**
     * Verify URL
     *
     * @param msgSignature Signature string
     * @param timeStamp Timestamp
     * @param nonce Random number
     * @param echoStr Random string
     * @return Decrypted echostr
     * @throws AesException Execution failed, please check the error code and specific error message of
     *         this exception
     */
    public String verifyUrl(String msgSignature, String timeStamp, String nonce, String echoStr)
            throws AesException {
        String signature = getSHA1(token, timeStamp, nonce, echoStr);

        if (!signature.equals(msgSignature)) {
            throw new AesException(AesException.ValidateSignatureError);
        }

        String result = decrypt(echoStr);
        return result;
    }

    /**
     * Decrypt message
     *
     * @param msgSignature Signature string
     * @param timeStamp Timestamp
     * @param nonce Random number
     * @param postData Encrypted XML
     * @return Decrypted XML
     * @throws AesException Execution failed, please check the error code and specific error message of
     *         this exception
     */
    public String decryptMsg(String msgSignature, String timeStamp, String nonce, String postData)

View on GitHub (pinned to 5e758547a8)