The difference between 401 and 403 — and why it breaks apps

A small thing that costs people an afternoon, from the HTTP guide I just uploaded.

401 Unauthorized means: I do not know who you are. Send credentials and try again. 403 Forbidden means: I know exactly who you are, and the answer is still no.

They feel interchangeable. They are not. A client is written to react to 401 by refreshing its token and retrying — that is the whole point of the code. It has no reason to do that for a 403.

So if your API returns 403 when a token has simply expired, the app never refreshes. The user sits on a screen that will not recover, closes it, opens it again, and gets the same thing. It looks like the login is broken. It is one digit.

Rule of thumb: could retrying with better credentials fix it? Then 401. Could nothing fix it short of someone changing their permissions? Then 403.

Full guide is in Web Development if it is useful.