JWT Token Expired: 9 Quick Fixes for Real 401 Errors

Step one: read the claims of the token behind the JWT token expired error

A JSON Web Token has three parts separated by dots: header, payload and signature. The first two are base64url encoded JSON, not encrypted, so anyone holding the token can read them. You need no key for that. Here is a real example I generated, with a lifetime of 15 minutes.

Sample token behind a JWT token expired error

CopyeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzQyIiwiYXVkIjoiYXBpLmV4YW1wbGUuY29tIiwiaWF0IjoxNzY3MjI1NjAwLCJleHAiOjE3NjcyMjY1MDAsInNjb3BlIjoicmVhZDpvcmRlcnMifQ.SOb9ntWowAoJACZ6_lINwtUOP2AnEFTsB-i3n227PxA

Decoded payload for the JWT token expired check

Copy{
  "iss": "https://auth.example.com",
  "sub": "user_42",
  "aud": "api.example.com",
  "iat": 1767225600,
  "exp": 1767226500,
  "scope": "read:orders"
}

The JWT Decoder does this split for you, labels each standard claim and shows a valid or expired badge computed from your local clock. Paste the token with or without the Bearer prefix.

Nine causes behind an expired or invalid token

Error wording for a JWT token expired failure differs between libraries. Node packages raise names such as TokenExpiredError, and PyJWT raises ExpiredSignatureError. The table maps what you see to the usual cause and the fix.

Clock skew: rejected on a fresh token

Two machines rarely agree to the second. If your validator runs 40 seconds ahead of the issuer, it declares a token dead 40 seconds early. Take the sample token with exp 1767226500.

On a 15 minute token that loss is a nuisance. On a token that lasts 60 seconds it can mean the token is dead on arrival. Most libraries offer a leeway or clock tolerance option, often set to something like 30 or 60 seconds. Use a small value and fix the clocks as well. A large leeway weakens expiry.

The milliseconds mistake

JavaScript time is in milliseconds, JWT time is in seconds. Developers who write Date.now() straight into exp create tokens that appear to last for millennia. Count the digits.

The reverse problem exists too. If a client multiplies exp by 1000 for a JavaScript date, a token with a 13 digit value ends up unreadable. Paste values into the Unix Timestamp Converter when you need to see the date behind a number.

A diagnostic order that saves time

1. Confirm the structureThe value must have three parts, or two for an unsigned token. If it does not, the problem is in how your client stores or sends it.
2. Read exp, nbf and iatConvert each to a date. Check the digit count first, so you spot milliseconds.
3. Compare with the validator clock that said JWT token expiredRun the date command on the server that rejected the token. A difference of more than a few seconds explains many intermittent failures.
4. Check aud and issCompare them character by character with the API settings. A trailing slash is enough to fail.
5. Check alg and kid in the headerThe algorithm must match what the server accepts. A kid that points to a rotated key explains a signature failure that started suddenly.
6. Verify on the serverUse your server side library with the right key. Only that step proves the token is genuine and not revoked.

Stop the error from reaching users

Fixing the cause is half the job. The other half is making sure a JWT token expired response does not become a visible failure. A short lived access token is supposed to expire, so the client should expect it and recover quietly.

Refresh a little early to avoid a JWT token expired error

Copyfunction needsRefresh(token, marginSeconds) {
  var payload = JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
  var now = Math.floor(Date.now() / 1000);
  return payload.exp - now < marginSeconds;
}
// refresh when fewer than 60 seconds remain
if (needsRefresh(accessToken, 60)) { accessToken = await refresh(); }

A margin of 60 seconds protects against small clock differences and slow networks. It also means the user never sees the moment of expiry. Keep the refresh call itself behind a lock, so ten parallel requests trigger one refresh and not ten.

Lifetimes are policy, not law. Your identity provider sets them, and the right values depend on how much damage a stolen token could do. The point is the pattern: short for access, longer for refresh, and a clear path from one to the other.

Related tools for the debugging session

If you want to see how a segment becomes text, the Base64 Encoder and Decoder shows the standard alphabet, while JWT swaps plus and slash for hyphen and underscore. To understand how a keyed signature is built, try the HMAC Generator.