Fast decision map: 401 vs 403 vs CORS

Start with this simple map before you change any code. Many beginners see the word “unauthorized” and assume every auth-looking error is the same. That is where the confusion starts.

The important difference is this: 401 and 403 are HTTP responses from the server. CORS is a browser access decision based on server response headers. Sometimes you will see both at once because the server returned a real error, but the browser refused to expose the body to JavaScript.

First question: did the browser receive a readable API response?

Do not start by changing the bearer token, rewriting the fetch call, or blaming React. Open DevTools and inspect the request in the Network tab. The console message is often only a summary. The Network tab tells you whether the browser sent a preflight request, whether the real request was sent, and whether the response was readable by JavaScript.

What 401 Unauthorized really means

A 401 Unauthorized response usually means the API needs valid authentication and did not receive it. The confusing part is the word “Unauthorized.” In beginner terms, treat 401 as “not successfully logged in for this request.” It usually points to identity, token, session, or credentials.

Common 401 causes

• The Authorization header is missing.
• The token is expired, revoked, malformed, copied incorrectly, or from the wrong environment.
• The request uses BearerTOKEN instead of Bearer TOKEN with a space.
• The frontend sends an API key in the wrong header name.
• The login cookie is not being sent because fetch credentials are not configured.
• The browser is calling the production API with a localhost or staging token.
• The API expects Basic auth but the frontend is sending a bearer token.
• A reverse proxy or gateway strips the Authorization header before the app receives it.

Example of a correct bearer token request in browser fetch:

const response = await fetch("https://api.example.com/v1/profile", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

Example of a 401-style response body:

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

A 401 should make you ask: “Did the API receive the correct identity proof?” That identity proof might be a bearer token, session cookie, API key, Basic auth value, signed request, or OAuth access token.

What 403 Forbidden really means

A 403 Forbidden response usually means the server understood the request but refuses to process it. In beginner terms, treat 403 as “the API knows enough to say no.” The user may be logged in, but the account, role, plan, IP, origin, or resource permission does not allow this action.

Common 403 causes

• The user is authenticated but does not have the required role, such as admin, owner, editor, or paid user.
• The token is valid but missing the required scope.
• The user is trying to access another user’s resource.
• The API key is valid but not allowed for that endpoint.
• The account plan does not include the feature.
• The API blocks requests from a region, IP range, domain, referrer, or origin.
• A WAF, firewall, CDN, or hosting security rule blocks the request.
• A WordPress nonce, CSRF token, or capability check fails.

Example of a 403-style response body:

{
  "error": "forbidden",
  "message": "You do not have permission to delete this project"
}

A 403 should make you ask: “Assuming the identity is known, is this identity allowed to do this specific action on this specific resource?”

What CORS really means

CORS is not the same thing as authentication. CORS is about whether browser JavaScript from one origin can access a response from another origin. Your request can have a perfect token and still fail if the API does not allow your frontend origin.

These are different origins:

http://localhost:5173
http://localhost:3000
https://app.example.com
https://api.example.com
https://example.com

If your frontend is running at http://localhost:5173 and your API is at https://api.example.com, the browser treats that as cross-origin. The API must return headers that allow the requesting origin to access the response.

Example CORS response for a browser frontend:

Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, Accept

Preflight makes this more confusing

For many API requests, the browser sends an OPTIONS request before the real request. This preflight asks the server whether the actual method and headers are allowed.

Example preflight request:

OPTIONS /v1/projects HTTP/1.1
Origin: http://localhost:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

Example successful preflight response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 600

If your auth middleware rejects that OPTIONS request with 401, the real POST may never happen. That is why a CORS problem can look like an auth problem and an auth problem can appear inside a CORS message.

How CORS can hide a real 401 or 403

Sometimes the server really does return a 401 or 403, but your frontend code cannot read the response body because CORS headers are missing. You may see a CORS console error instead of the useful JSON message.

For example, the server might return this:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Token expired"
}

But if the response does not include the correct Access-Control-Allow-Origin header for the browser origin, JavaScript may not be allowed to read the JSON body. The console may focus on CORS, even though the underlying API problem is an expired token.

This is why the Network tab matters. It can show you the response status and headers even when your frontend code only receives a generic fetch failure.

The safest debugging order

Use this order when you are confused. It prevents you from fixing the token when the real problem is preflight, or changing CORS when the real problem is a missing role.

Practical examples

Example 1: 401 because the bearer token is missing

Bad request:

const response = await fetch("https://api.example.com/v1/profile", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

Better request:

const response = await fetch("https://api.example.com/v1/profile", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

If this changes the result from 401 to 200, the problem was authentication. If it changes the result to a CORS preflight error, then the server may not allow the Authorization header in CORS.

Example 2: CORS because Authorization is not allowed in preflight

The browser asks:

Access-Control-Request-Headers: authorization

The server must allow it:

Access-Control-Allow-Headers: Authorization, Content-Type, Accept

If the server only allows Content-Type but not Authorization, the browser can block the request before your endpoint logic runs.

Example 3: 403 because the user is logged in but lacks permission

This request may include a valid token:

const response = await fetch("https://api.example.com/v1/admin/users", {
  method: "GET",
  headers: {
    "Authorization": "Bearer VALID_NON_ADMIN_TOKEN",
    "Accept": "application/json"
  }
});

But the API may still return:

{
  "error": "forbidden",
  "message": "Admin role required"
}

Changing the token format will not help if the token is already valid but belongs to a user without admin permission.

Example 4: Cookie session works in browser page, fails in fetch

If the API uses cookies, browser fetch may need credentials:

const response = await fetch("https://api.example.com/v1/account", {
  method: "GET",
  credentials: "include",
  headers: {
    "Accept": "application/json"
  }
});

The server also needs to allow credentials correctly:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true

Do not use a wildcard origin for credentialed browser requests. Use the real frontend origin.

React, Vue, Axios, and frontend app notes

The same debugging logic applies whether you use fetch, Axios, React Query, Vue, Angular, or plain JavaScript. The library may change how the request is written, but it does not remove browser security rules.

Axios example with bearer token:

const response = await axios.get("https://api.example.com/v1/profile", {
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    Accept: "application/json"
  }
});

Axios example with cookies:

const response = await axios.get("https://api.example.com/v1/account", {
  withCredentials: true,
  headers: {
    Accept: "application/json"
  }
});

If Axios says Network Error, do not assume the server is down. It may be a CORS block where the browser refused to expose the response. Open the Network tab and check whether the request, preflight, or response headers tell the real story.

WordPress API debugging note

WordPress users can hit the same problem from custom JavaScript, plugins, shortcode output, custom HTML blocks, or page builder widgets. If the request runs in the visitor’s browser, CORS applies. If the request runs through PHP on the server side, browser CORS is usually not the same issue.

Frontend JavaScript call from a WordPress page:

fetch("https://api.example.com/v1/data", {
  headers: {
    "Authorization": "Bearer PUBLIC_OR_USER_TOKEN",
    "Accept": "application/json"
  }
});

Server-side WordPress request:

$response = wp_remote_get('https://api.example.com/v1/data', array(
  'headers' => array(
    'Authorization' => 'Bearer SERVER_SIDE_TOKEN',
    'Accept' => 'application/json',
  ),
  'timeout' => 20,
));

For private API keys, server-side WordPress code is usually safer than exposing the key in public JavaScript. Browser users can inspect JavaScript, network requests, and visible tokens.

Common symptoms and what to check

Bad fixes that waste time

Some fixes appear often in forum threads but do not solve the real issue. Avoid these unless you fully understand the tradeoff.

Copyable debugging checklist

Use this when you need to explain the issue to a teammate, instructor, support team, or future version of yourself.

API auth and CORS debugging note

Frontend origin:
Example: http://localhost:5173

API URL:
Example: https://api.example.com/v1/projects

Request method:
GET / POST / PUT / PATCH / DELETE

Tool comparison:
Works in Postman? Yes / No
Works in cURL? Yes / No
Fails in browser? Yes / No

Browser Network tab:
Failed row is OPTIONS or real request?
OPTIONS status:
Real request status:
Console error:

Authentication type:
Bearer token / API key / cookie session / Basic auth / OAuth

Request headers:
Authorization:
Content-Type:
Accept:

Credential settings:
fetch credentials or Axios withCredentials:
Cookie present in request? Yes / No

CORS response headers:
Access-Control-Allow-Origin:
Access-Control-Allow-Methods:
Access-Control-Allow-Headers:
Access-Control-Allow-Credentials:

If status is 401:
Token present?
Token expired?
Wrong environment?
Wrong auth scheme?
Cookie missing?

If status is 403:
User role:
Required role or scope:
Resource owner:
Plan or feature restriction:
IP, origin, WAF, or firewall rule:

What changed recently:
New frontend domain / new API domain / deployment / token refresh / auth middleware / proxy / CDN / plugin

Related CodeZips tools for this problem

Use these tools when you want to turn the error into a clear checklist, support note, or next debugging step.

Technical references used for this guide

This guide is written as a practical debugging workflow, with status-code and browser-security behavior checked against web platform documentation.

• MDN Web Docs: 401 Unauthorized
• MDN Web Docs: 403 Forbidden
• MDN Web Docs: Cross-Origin Resource Sharing
• MDN Web Docs: Preflight request
• MDN Web Docs: Access-Control-Allow-Origin
• MDN Web Docs: Access-Control-Allow-Credentials