Státní API vrací 200 + HTML místo JSON — frontend URL místo backend endpointu

import { Aside } from ‘@astrojs/starlight/components’;

U externích API nikdy nevaliduj jen HTTP status — ověř Content-Type `application/json`, a backend URL otestuj z Node (ne jen curl/prohlížeč), protože SPA frontend vrací 200 + HTML na jakoukoli cestu.

Symptom

Server-side proxy route na státní registr (ARES) vracela 502 „Chyba při komunikaci s API”, přestože stejné IČO fungovalo při client-side lookupu z prohlížeče. curl na tutéž URL vracel 200, takže endpoint vypadal zdravě.

Root cause

Route používala frontend cestu webové aplikace registru místo backend REST endpointu:

❌ https://ares.gov.cz/ekonomicke-subjekty-v-registru-ekonomickych-subjektu/rest/ekonomicke-subjekty/{ico}
✅ https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/{ico}

Frontend je SPA — na jakoukoli cestu vrací 200 OK s HTML shellem aplikace. Kontrola response.ok tedy prošla, ale response.json() spadl na Unexpected token '<' a catch blok chybu přemapoval na generické 502. Diagnostiku zdrželo to, že curl -o /dev/null -w '%{http_code}' ukazoval 200 (HTML se nezobrazilo) — vypadalo to jako problém v Node fetch, ne v URL.

Fix

`https://ares.gov.cz/ekonomicke-subjekty-v-registru-ekonomickych-subjektu/rest/ekonomicke-subjekty/${ico}`
`https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/${ico}`

Backend endpoint (-v-be = backend) vrací čistý JSON. Po opravě lookup funguje server-side i client-side.

Jak se tomu vyvarovat v jiných systémech

• Detection: při ladění externího API vždy vypsat prvních ~200 znaků body, ne jen status kód. <!DOCTYPE v odpovědi = mluvíš s frontendem.
• Anti-pattern: if (!response.ok) … else response.json() bez kontroly Content-Type — SPA/WAF/error stránky vrací 200 + HTML.
• Lepší přístup: guard if (!response.headers.get('content-type')?.includes('application/json')) throw … před parsováním; backend URL převzít z funkčního kódu/oficiální dokumentace, ne odhadovat z URL webové aplikace.

Sister bugs / související

• WAF/bot-protection stránky se chovají stejně (200 + HTML challenge) — stejný guard pomáhá.
• pohoda-xml-date-tostring — další past v integraci na české ekosystémové API.