Authentication header reference
WWW-Authenticate header: read the API authentication challenge
Parse Bearer and Basic authentication challenges, realms, OAuth token errors, scope hints, and multiple WWW-Authenticate values.
A 401 response should normally include a challenge describing how to authenticate. Do not discard it. The scheme, realm, error, error_description, and scope parameters often say more than the JSON body, and multiple challenges may be supplied.
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
Split challenges correctly
Quoted commas can appear inside parameters, so a naive comma split can corrupt multiple challenges.
- 02
Match the scheme
Confirm the client uses the advertised Bearer, Basic, Digest, or other scheme for this endpoint.
- 03
Handle OAuth detail
Use invalid_token to refresh or replace credentials; use insufficient_scope to request or configure the missing permission.
401 returned; client ignores all response headers
WWW-Authenticate: Bearer error="invalid_token" → refresh credential path
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 challenge 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 — WWW-Authenticate. Recheck your pinned provider/API version before production deployment.