---
title: Graceful fallback on /api/chat when the Gateway is down
description: When the AI Gateway is down or the request is malformed, /api/chat now returns a 503 JSON envelope pointing agents to /llms-full.txt, /api/mcp, and /.well-known/mcp.json instead of a bare 500.
section: meta
tags: [meta, changelog, chat, api, agents, mcp, resilience, ai-gateway]
genre: index
lastUpdated: 2026-04-23
url: https://fardiniqbal.com/docs/changelog/2026-04-23-chat-fallback-envelope
---


When the AI Gateway is unreachable or the request body is malformed, `/api/chat` used to throw a 500 with whatever stack trace leaked out. Now it returns a 503 JSON envelope with `code: "ai-gateway-unavailable"`, a one-line human message, and pointers to `/llms-full.txt`, `/api/mcp`, and `/.well-known/mcp.json`. A `Retry-After: 60` header rides along for the well-behaved clients that respect it.

The point isn't the status code — it's the envelope. If an agent hits the chat endpoint during an outage, a 500 tells it nothing; a 503 with three URLs tells it where the same information lives without the stream. The site's chat surface is one of four ways to read me, and the other three keep working when the Gateway doesn't. The endpoint should say so. Covered by `tests/e2e/chat-fallback.spec.ts`.