Every developer has been there. You send a perfectly crafted API request with what you believe is a valid token, and the server fires back a cold, unhelpful 401 Unauthorized response. If you are trying to figure out how to fix 401 unauthorized error when calling API with token requests, you are in the right place.
I have spent years debugging authentication failures across REST APIs, OAuth flows, and microservice architectures. The 401 error is the single most common API authentication problem developers face, and it can stem from dozens of root causes ranging from a simple typo in a header to subtle clock skew between servers.
This guide breaks down exactly what a 401 means, how it differs from a 403, and walks through a step-by-step troubleshooting process you can follow right now. You will learn how to debug with curl, inspect JWT claims, handle token refresh properly, and prevent these errors from recurring in production.
Whether you are working with Bearer tokens, JWTs, API keys, or OAuth 2.0 flows, the fixes below apply. Let us get your API calls working again.
Table of Contents
What Is a 401 Unauthorized Error?
A 401 Unauthorized error is an HTTP status code defined in RFC 9110 that means the server rejected your request because it lacked valid authentication credentials. When an API returns 401, it is telling you that it does not recognize the identity of whoever made the request.
The response almost always includes a WWW-Authenticate header that tells you what authentication scheme the server expects. This header is your first clue, because it specifies whether the API needs Bearer tokens, Basic Auth, or a custom scheme.
It is important to understand that 401 does not necessarily mean your token is wrong. It means the server could not verify your identity. The token might be expired, malformed, signed with the wrong key, or simply missing from the request entirely.
For API developers, 401 is the correct response when no valid credentials are present. If credentials are valid but the user lacks permission for a specific resource, the server should return 403 Forbidden instead.
How to Fix a 401 Unauthorized Error (Step-by-Step)
Follow these seven steps to fix a 401 Unauthorized error on API calls. Each step targets a different common cause, so work through them in order until your request succeeds.
Step 1: Verify the Authorization header is present and correctly formatted. Check that your request includes an Authorization header with the right scheme. For Bearer tokens, the format must be Authorization: Bearer YOUR_TOKEN with a single space after “Bearer” and no extra characters.
Step 2: Check if the token has expired. JWT tokens include an exp claim that defines when they stop working. Decode the token and compare the exp timestamp to the current time. If it has passed, request a new access token using your refresh token.
Step 3: Confirm the token type matches what the API expects. Some APIs accept Bearer tokens, others expect API keys in a custom header like X-API-Key. Sending the wrong type of credential produces a 401 even when the value itself is valid.
Step 4: Inspect the token claims for scope and audience mismatches. Even a valid, non-expired JWT can trigger a 401 if its aud (audience) claim does not match the API’s identifier, or if the scope claim does not include the required permission.
Step 5: Check for clock skew between your server and the API server. If your server clock is off by even 30 seconds, a JWT that looks valid to you may appear expired to the API. Use NTP synchronization and consider adding clock skew leeway in your JWT validation logic.
Step 6: Rule out proxy or CDN interference. Some reverse proxies, CDNs, or API gateways strip the Authorization header before forwarding the request. Check your proxy configuration and test the API call directly to isolate the issue.
Step 7: Decode the WWW-Authenticate response header. The 401 response body and headers often contain specific error codes like invalid_token, invalid_request, or insufficient_scope. These codes tell you exactly what went wrong and which fix to apply.
401 vs 403 Forbidden: The Key Difference
The difference between 401 and 403 comes down to identity versus permission. A 401 means the server does not know who you are. A 403 means the server knows who you are, but you are not allowed to access the resource.
Many developers confuse these two status codes, which leads to incorrect fixes. If you send a valid token and still get 401, the issue is authentication. If you send a valid token and get 403, the issue is authorization or permissions.
Here is a side-by-side comparison to help you distinguish them quickly.
401 Unauthorized: Missing, expired, or invalid credentials. The fix is to authenticate or re-authenticate. The response includes a WWW-Authenticate header.
403 Forbidden: Valid credentials but insufficient permissions. The fix is to request elevated access or use a different account. No WWW-Authenticate header is returned.
Understanding this distinction saves hours of debugging. If your token is valid but you still get 401, check for malformed headers or token type mismatches rather than chasing permission issues.
Common Causes of 401 Errors With API Tokens
Most 401 errors fall into a handful of categories. Knowing these causes helps you narrow down the problem quickly instead of guessing.
Expired access token: This is the number one cause. Access tokens are short-lived by design, often expiring in 15 minutes to 1 hour. When the exp claim passes, every request using that token returns 401 until you refresh it.
Malformed Authorization header: A missing space, a typo like “Barer” instead of “Bearer”, or trailing whitespace can all cause the server to reject the header. The format is strict and unforgiving.
Wrong API key or revoked key: If you recently rotated your API keys, old keys may still be in use by some services. A revoked key returns 401 immediately, even if it worked minutes ago.
Token signed with the wrong key: When an identity provider rotates its signing keys, tokens signed with the old key become invalid. If your application has not fetched the new JWKS (JSON Web Key Set), it will reject otherwise-valid tokens.
Clock skew: A server clock that drifts even slightly can cause token validation to fail. The server thinks the token is expired or not-yet-valid, even though it looks fine on your end.
Audience or issuer mismatch: A JWT contains aud (audience) and iss (issuer) claims. If these do not match what the API expects, the token is rejected with 401.
Insufficient scope: Some APIs return 401 when the token lacks the required scope, though technically this should be a 403. Always check the API documentation for how it handles scope violations.
How to Fix 401 Unauthorized Error When Calling API With Token
Different authentication methods require different fixes. Here is how to resolve 401 errors for the most common token types.
JWT Bearer tokens: Decode the token and inspect the exp, aud, iss, and kid claims. If expired, call your refresh token endpoint. If the audience is wrong, regenerate the token with the correct audience parameter. If the kid does not match the current JWKS, fetch the latest keys.
API keys: Verify the key is active in your dashboard and has not been rotated or revoked. Check that you are sending it in the correct header or query parameter, since some APIs use X-API-Key while others use Authorization with a custom scheme.
OAuth 2.0 access tokens: If the token was obtained through client credentials flow, ensure the client ID and secret are correct. If using authorization code flow, verify the redirect URI and that the token exchange completed successfully.
Basic Authentication: The credentials must be Base64-encoded as username:password and sent as Authorization: Basic BASE64_STRING. A common mistake is encoding the string incorrectly or including a newline character.
How to Debug 401 Errors With curl and Browser DevTools
When a 401 error appears, you need tools to inspect what is actually being sent and received. Here are the most effective debugging techniques.
Use curl with verbose output. The curl -v flag shows the full request and response headers, including the Authorization header you are sending and the WWW-Authenticate header the server returns. This is the fastest way to confirm your token is actually being transmitted.
Example command:
curl -v -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/resource
Decode JWT tokens manually. A JWT has three Base64-encoded parts separated by dots. You can decode the payload (middle part) using a command-line tool or an online debugger like jwt.io. Look for the exp claim and compare it to the current Unix timestamp.
To decode a JWT payload in your terminal:
echo YOUR_JWT | cut -d. -f2 | base64 -d 2>/dev/null | jq .
Check the Network tab in browser DevTools. Open Chrome or Firefox DevTools, go to the Network tab, and reproduce the failing request. Inspect the request headers to confirm the Authorization header is present and correctly formatted. Then check the response headers for the WWW-Authenticate error code.
Test in Postman separately. If your application gets 401 but Postman succeeds, the issue is in how your code constructs the request. Compare the headers Postman sends with what your application sends, paying attention to encoding, content type, and header casing.
401 Error Variations and What They Mean
The WWW-Authenticate header in a 401 response carries specific error information that tells you exactly what went wrong. Learning to read these codes accelerates debugging significantly.
invalid_token: The token was malformed, expired, or signed with an unrecognized key. This is the most common error code. Check expiry, signature, and key rotation status.
invalid_request: The request itself was malformed, often because the Authorization header was missing, used the wrong scheme, or contained syntax errors. Fix the header format.
insufficient_scope: The token is valid but does not have the permissions required for the requested resource. You need to request a token with the appropriate scope.
Beyond these OAuth-specific codes, some APIs and web servers return numeric sub-codes. For example, IIS uses codes like 401.1 (logon failed), 401.2 (logon failed due to server configuration), and 401.3 (unauthorized due to ACL on resource). These sub-codes are specific to the server implementation and can point you toward configuration-level issues.
Always read the full response body, not just the status code. Many APIs include a JSON error object with a message or detail field that provides additional context beyond what the standard headers convey.
How to Prevent 401 Errors in Your API
Fixing a 401 error in the moment is necessary, but preventing it from happening again is even more valuable. Here are proven strategies to keep your API authentication working smoothly.
Implement automatic token refresh. Build an interceptor in your HTTP client that detects 401 responses and automatically calls the refresh token endpoint before retrying the original request. This pattern is widely used in JavaScript, Python, and other languages.
A simple JavaScript refresh interceptor checks for a 401 status, pauses subsequent requests, refreshes the token, and then replays all queued requests with the new token. This eliminates the vast majority of user-facing 401 errors.
Handle refresh token race conditions. When multiple API calls fail with 401 simultaneously, they can all trigger a refresh at the same time, causing cascading failures. Deduplicate refresh requests by using a shared promise or lock so only one refresh occurs at a time.
Monitor for 401 spikes. Set up alerting that triggers when 401 error rates exceed a threshold. A sudden spike often indicates a key rotation that has not propagated, a signing key change, or a configuration deployment that broke authentication.
Plan for signing key rotation. If your identity provider rotates JWT signing keys, your application must periodically fetch the JWKS endpoint to stay current. Implement a background refresh of JWKS with caching and graceful fallback.
Add clock skew tolerance. When validating JWTs server-side, include a small leeway window (typically 30 to 60 seconds) to account for minor clock differences between servers. Most JWT libraries support a clockTolerance option.
Return clear error messages. If you build APIs, include specific error codes and human-readable messages in your 401 responses. Developers integrating with your API will thank you, and your support burden will drop significantly.
Frequently Asked Questions
How to fix 401 unauthorized error API?
To fix a 401 unauthorized error on an API, check that your Authorization header is present and correctly formatted, verify your token has not expired, confirm you are using the correct authentication scheme (Bearer, API key, Basic Auth), and inspect the WWW-Authenticate response header for specific error codes like invalid_token or insufficient_scope.
What is error code 401 on token?
Error code 401 on a token means the server received your token but could not validate it. The token may be expired, malformed, signed with the wrong key, or lack the required audience or scope claims. The server returns 401 along with a WWW-Authenticate header explaining the specific problem.
How to fix 401 authorization required error?
Fix a 401 authorization required error by ensuring valid credentials are sent with every request. Check that your token or API key is current, the Authorization header uses the correct scheme and formatting, and the token has not been revoked or rotated. If using JWT, decode it and verify the exp, aud, and iss claims match the API requirements.
What is API call failed with status 401?
An API call failing with status 401 means the server rejected the request due to missing or invalid authentication credentials. The request reached the server, but the token, API key, or other credentials provided were not accepted. Common causes include expired tokens, malformed headers, wrong key types, and clock skew between client and server.
Why does my Bearer token return 401 even though it is not expired?
A non-expired Bearer token can return 401 if the audience claim does not match the API, the signing key has been rotated and your application has not fetched the new JWKS, the token lacks the required scope, the header is malformed, or a proxy is stripping the Authorization header before the request reaches the API.
How do I check if my JWT token is expired?
Decode the JWT payload by Base64-decoding the middle segment between the two dots. Look for the exp claim, which is a Unix timestamp. Compare it to the current time. If the current time is greater than exp, the token is expired and you need to request a new one using your refresh token.
Can a CDN or proxy cause 401 errors on API calls?
Yes. Some CDNs, reverse proxies, and API gateways strip or modify the Authorization header before forwarding requests. This is a common cause of 401 errors that only appear in production. Test the API call directly, bypassing the proxy, and check your proxy configuration to ensure the Authorization header is passed through unchanged.
Why do I get 401 after refreshing my token?
Getting 401 immediately after a token refresh usually indicates a race condition where multiple requests fire before the new token propagates, a propagation delay in distributed systems, or the refresh endpoint itself returning an invalid token. Deduplicate refresh calls with a shared lock and ensure the new token is applied to all pending requests before retrying.
Conclusion
The 401 Unauthorized error is frustrating but almost always traceable to a specific, fixable cause. By methodically checking your Authorization header format, token expiry, claim validity, clock skew, and proxy configuration, you can resolve the vast majority of these errors in minutes rather than hours.
The most valuable habit you can build is reading the WWW-Authenticate response header. It tells you whether the problem is an expired token, a malformed request, or an insufficient scope, eliminating most of the guesswork.
For long-term reliability, implement automatic token refresh with race condition handling, monitor for 401 spikes, and plan ahead for signing key rotations. These preventive measures keep your API integrations running smoothly even as tokens expire and keys change.
If you found this guide on how to fix 401 unauthorized error when calling API with token requests helpful, bookmark it for the next time authentication breaks. The step-by-step checklist works for any token-based API, whether you are using JWT, Bearer tokens, API keys, or OAuth 2.0.