Fix a browser CORS error at the API boundary

An API responds in a command-line client but the browser refuses to expose its response. The frontend reports a network error even though the server may have received the request.

Why this happens

Browsers enforce cross-origin access rules. Missing or incompatible response headers, failed preflight requests and credential configuration can block access; command-line clients do not enforce the same browser policy.

Step-by-step solution

1. Inspect the browser console and the OPTIONS request, if present. Confirm the exact frontend origin, including scheme and port.

2. Configure the API to allow the intended origin, methods and headers. If cookies are used, configure credentials consistently and use an explicit allowed origin rather than a wildcard.

3. Retest the actual browser request. Do not use mode='no-cors' to read an API response: an opaque response does not solve that requirement.

Worked example

http://localhost:3000 and http://localhost:8000 are different origins. A server allowlist must match the frontend origin, not the URL path of the API endpoint.

Verify the fix

A permitted origin should read the response, while an unapproved origin should remain blocked. Check both successful and error responses for the required headers.

Prevent a repeat

Keep development and production origins explicit. Distinguish a CORS failure from an unavailable server or an invalid TLS certificate before changing policy.

Reference

Official documentation or standards guidance

An original Gistmax troubleshooting guide. Scenarios and sample values are illustrative; configuration depends on your software version and environment. Cover diagram: Gistmax Tutorials.