{"record":{"id":"87f743a28b621827","repo":"HMCL-dev/HMCL","slug":"https-api-minecraftservices-com-entitlements-mcs","errorCode":null,"errorMessage":"https://api.minecraftservices.com/entitlements/mcstore","messagePattern":"https://api\\.minecraftservices\\.com/entitlements/mcstore","errorType":"http","errorClass":"ResponseCodeException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/auth/microsoft/MicrosoftService.java","lineNumber":172,"sourceCode":"        getUhs(minecraftXstsResponse, uhs);\n\n        // Authenticate with Minecraft\n        MinecraftLoginWithXBoxResponse minecraftResponse = HttpRequest\n                .POST(\"https://api.minecraftservices.com/authentication/login_with_xbox\")\n                .json(mapOf(pair(\"identityToken\", \"XBL3.0 x=\" + uhs + \";\" + minecraftXstsResponse.token)))\n                .retry(5)\n                .accept(\"application/json\").getJson(MinecraftLoginWithXBoxResponse.class);\n\n        long notAfter = minecraftResponse.expiresIn * 1000L + System.currentTimeMillis();\n\n        // Check MC ownership, this is necessary, see GitHub#2979\n        HttpURLConnection request = HttpRequest.GET(\"https://api.minecraftservices.com/entitlements/mcstore\")\n                .authorization(\"Bearer \" + minecraftResponse.accessToken)\n                .retry(5)\n                .accept(\"application/json\").createConnection();\n\n        if (request.getResponseCode() != 200) {\n            throw new ResponseCodeException(\"https://api.minecraftservices.com/entitlements/mcstore\", request.getResponseCode());\n        }\n\n        // Get Minecraft Account UUID\n        MinecraftProfileResponse profileResponse = getMinecraftProfile(minecraftResponse.tokenType, minecraftResponse.accessToken);\n        handleErrorResponse(profileResponse);\n\n        return new MicrosoftSession(minecraftResponse.tokenType, minecraftResponse.accessToken, notAfter, liveRefreshToken,\n                new MicrosoftSession.User(minecraftResponse.username), new MicrosoftSession.GameProfile(profileResponse.id, profileResponse.name));\n    }\n\n    public Optional<MinecraftProfileResponse> getCompleteProfile(String authorization) throws AuthenticationException {\n        try {\n            return Optional.ofNullable(\n                    HttpRequest.GET(\"https://api.minecraftservices.com/minecraft/profile\")\n                            .authorization(authorization).getJson(MinecraftProfileResponse.class));\n        } catch (IOException e) {\n            throw new ServerDisconnectException(e);\n        } catch (JsonParseException e) {","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/auth/microsoft/MicrosoftService.java#L154-L190","documentation":"During Microsoft authentication HMCL checks the purchased entitlements via GET https://api.minecraftservices.com/entitlements/mcstore. Any non-200 response is raised as ResponseCodeException with the endpoint URL as its message, aborting authentication because ownership of Java Edition could not be confirmed.","triggerScenarios":"authenticateViaLiveAccessToken (via authenticate or refresh) gets a status other than 200 from the mcstore entitlements endpoint after 5 retry attempts; token was valid for the login step but rejected here; Mojang service outage; rate limiting or 5xx from minecraftservices.","commonSituations":"Temporary Mojang/minecraftservices outage or maintenance; account without Java Edition entitlement hitting the endpoint; corporate/firewall proxy intercepting HTTPS and returning an error page; expired access token due to clock skew or long delay between steps.","solutions":["Retry authentication later — transient 5xx/outages on minecraftservices.com are common and clear on their own","Check https://xboxstatus.com / Mojang status pages for service incidents","Verify the account actually owns Minecraft: Java Edition or has an active Game Pass for PC subscription","Check network/proxy settings: disable VPN or corporate proxy that could intercept api.minecraftservices.com, then retry"],"exampleFix":"// before: single-shot authentication with no retry handling\naccount.logIn();\n// after: tolerate transient entitlement-check failures\ntry {\n    account.logIn();\n} catch (ResponseCodeException e) {\n    if (String.valueOf(e.getMessage()).contains(\"entitlements/mcstore\")) {\n        Thread.sleep(5000); // wait and retry — mcstore is often transiently unavailable\n        account.logIn();\n    } else {\n        throw e;\n    }\n}","handlingStrategy":"retry","validationCode":"// pre-check entitlements independently before full login\nHttpURLConnection c = HttpRequest.GET(\"https://api.minecraftservices.com/entitlements/mcstore\")\n        .authorization(\"Bearer \" + accessToken)\n        .createConnection();\nif (c.getResponseCode() != 200) { warnUserEntitlementCheckUnavailable(); }","typeGuard":null,"tryCatchPattern":"try {\n    account.logIn();\n} catch (ResponseCodeException e) {\n    if (String.valueOf(e.getMessage()).contains(\"entitlements/mcstore\")) {\n        Thread.sleep(10_000); // transient mcstore failure — retry with backoff\n        account.logIn();\n    } else throw e;\n}","preventionTips":["Check Mojang/Xbox status pages during incidents","Disable VPN/proxies that may intercept api.minecraftservices.com","Confirm the account owns Java Edition before login","Use exponential backoff for automated retries"],"tags":["network","http","microsoft","entitlements"],"backgroundTag":"http-error-response","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}