How to fix server error on Next.js (Headless)

Steps for Next.js (Headless)

1. Audit 5xx sources: check Vercel/server logs, or add a global fetch wrapper that logs non-2xx responses from your commerce API (e.g. in lib/fetcher.ts). Identify which routes (App Router pages, Route Handlers, or getServerSideProps functions) are throwing unhandled errors.
2. For App Router routes, add an `error.tsx` (client boundary) AND a `global-error.tsx` at the `app/` root so uncaught render errors return a recoverable UI instead of a 500. Pair each with a `not-found.tsx` to avoid conflating 404s with 5xxs.
3. For Route Handlers (`app/api/*/route.ts`) and legacy `pages/api/*` handlers, wrap all logic in try/catch and return explicit `NextResponse.json({ error: '...' }, { status: 500 })` — never let an unhandled promise rejection propagate, which causes Next.js to emit a bare 500 with no body.
4. For `getServerSideProps` pages (pages/ router), wrap the entire function body in try/catch. On a caught error, either `return { props: { error: true } }` (renders a degraded page with 200) OR use `res.status(500)` only when the page is genuinely unserviceable — prefer a degraded 200 over a 500 for SEO.
5. Harden commerce-API calls: add retry logic with exponential back-off (e.g. using `p-retry`) and set explicit `next: { revalidate }` / `cache` options so a single upstream blip does not bust the entire render. For ISR pages, returning stale content is always better than a 500.
6. Deploy, then validate with `curl -I https://<your-domain>/affected-path` and confirm HTTP 200 (or 404 where appropriate). Re-submit affected URLs in Google Search Console via the URL Inspection tool to trigger re-crawl.

What is server error?

An HTTP 500 (or any 5xx) response means your web server encountered an error and could not deliver the page — instead of your store content, visitors and search-engine crawlers receive an error message. Common culprits include broken app/plugin code, a crashed database connection, exhausted server memory, a misconfigured hosting environment, or a recent theme/code change that introduced a bug. Unlike a 404 ("page not found"), a 5xx error tells crawlers the page should exist but the server failed to produce it.

Google explicitly drops URLs from its index when they persistently return 5xx errors — your products, categories, and blog posts simply disappear from search results, costing you organic traffic and revenue. Even intermittent 5xx errors waste your crawl budget: Googlebot retries and eventually de-prioritises your site, slowing the indexing of new and updated pages. Shoppers who land on a broken page immediately leave, driving up bounce rates and signalling poor quality to both users and search engines. If high-revenue pages stay broken long enough, recovering their rankings can take weeks or months even after the fix.

See the complete Server error guide for every platform and the full background.