Proxying APIs and Handling SPA Fallback on Netlify with netlify.toml

When you deploy a static site on Netlify, you can avoid CORS errors and SPA 404s by configuring edge‑level rewrite rules in netlify.toml. A rewrite with status 200 fetches the upstream content and returns it while keeping the original URL in the browser.

Worked configuration

[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200
  force = true

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

How it works

• The first rule matches any path beginning with /api/. The :splat variable captures the remainder (users, data/1, etc.) and appends it to the upstream URL. force = true makes the rule take precedence over a file with the same name in the publish directory.
• The second rule is a catch‑all that returns /index.html with a 200 status for every other request, allowing a client‑side router to handle the URL without a hard 404.

Verification

After deploying, check that the proxy is a rewrite, not a redirect:

curl -I https://YOUR_SITE.netlify.app/api/users

Look for:

• HTTP/2 200 (or HTTP/1.1 200 OK)
• No Location header.
• Presence of a Netlify‑specific header such as x-netlify (optional).

In the browser devtools Network tab, the request URL should remain under your domain and the response should contain the API data without CORS errors.

Limits and common mistakes

Rule order

Netlify evaluates redirects top‑down. Placing the catch‑all /* rule before the /api/* proxy will shadow the API path, causing all /api/ requests to return index.html. Always put specific rules above generic ones.

Status code choice

Using 301 or 302 for the API rule triggers a browser redirect, which exposes the upstream URL and re‑introduces CORS problems. Keep the status at 200 for a true rewrite.

Bandwidth and latency

Because Netlify fetches the upstream response on each request, the data counts toward your site’s bandwidth and adds the upstream latency to the response time. Monitor usage if the proxy handles high traffic.

Static nature

These rules are fixed at deploy time. If you need to make routing decisions based on headers, cookies, or authentication tokens, you must use Netlify Edge Functions or serverless functions instead.