Authentication field note
API 401 vs 403: credential failure or permission failure?
Use the status, WWW-Authenticate challenge, token state, and resource policy to separate API 401 Unauthorized from 403 Forbidden.
Treat 401 as an authentication investigation first: the server lacks acceptable credentials for this request. Treat 403 as an authorization or policy investigation after confirming identity. Providers sometimes blur the distinction to avoid leaking resource existence, so the body and challenge headers still matter.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Check the challenge
Read WWW-Authenticate for the expected scheme, realm, and any bearer-token error details.
- 02
Validate the credential path
Confirm the token is sent to the intended host, has not expired, belongs to the correct environment, and uses the required prefix or scheme.
- 03
Then inspect permissions
For a valid identity, compare scopes, role, resource ownership, organization policy, IP rules, and endpoint-specific restrictions.
401 + WWW-Authenticate: Bearer error="invalid_token"
Credential rejected → refresh or replace token 403 with valid token → inspect scope and resource policy
Evidence
HTTP 429: A rate, quota, concurrency, or resource lock limit blocked the request.
Retry-After is present; it should take precedence over a guessed delay.
The reported request window has no remaining capacity.
Next checks
01Parse Retry-After as either delta-seconds or an HTTP date before scheduling the next attempt.
No account · no upload · no endpoint calledOpen the full incident decoder and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every authentication response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the MDN — 401 Unauthorized. Recheck your pinned provider/API version before production deployment.