Recipe

Respond to a 401 cleanly

A partner 401 has two causes: an expired token (re-mint and retry once) or an invalid credential (fix it — do not loop). Telling them apart is the difference between resilience and a retry storm.

2 min read

ExpiredRe-mint once

InvalidFix credential

No loopCap retries

Two very different 401s

A 401 on the partner ring means your token was not accepted. If it merely expired between your check and the call, the fix is to mint a fresh token and retry the request exactly once. If the credential is wrong or revoked, re-minting fails too — retrying just burns your token-endpoint quota.

Handle it in code

let res = await call(token);
if (res.status === 401 && !alreadyRetried) {
  token = await mintToken();   // re-mint once
  res = await call(token);     // retry exactly once
}
if (res.status === 401) throw new AuthError('credential invalid');

The one-shot retry covers expiry; a second 401 is a real credential fault to surface, not retry.

Then check scope

If the call returns 403 rather than 401, the token is valid but lacks the scope — that is a configuration fix (request the scope), not a retry. See the partner error table.

Frequently asked questions

Should I retry every 401?

No — only once, and only for a suspected expiry. Re-mint a token and retry the request a single time. A second 401 means the credential itself is bad; surface it rather than looping.

How is a 403 different from a 401 here?

401 means the token was not accepted (expired or invalid). 403 means the token is valid but lacks the required scope — fix that by requesting the scope, not by retrying.