Een lege pagina na een mislukte APIrequest

De pagina zelf laadt, maar het deel dat van de API afhangt blijft leeg. De HTML-respons is geslaagd, de mislukte aanroep gebeurt daarna in de browser. Een monitoringtool die alleen de statuscode van de pagina bekijkt, ziet niets verkeerds. De bezoeker ziet wel een gat.

De MDN-overzichtspagina over webprestaties koppelt prestaties aan de ervaren reactie van de site, ook bij trage of onbetrouwbare verbindingen. Een lege plek zonder uitleg kan voor een bezoeker op een kapotte site lijken, ongeacht de oorzaak. Dat is een redactionele inschatting, geen uitspraak van de bron. Wat telt is dus niet alleen of de pagina laadt, maar wat de bezoeker te zien krijgt als een onderdeel faalt.

Test in een browser met ontwikkelaarstools. De exacte menunamen verschillen per browser en versie, dus zoek in jouw tools naar opties voor het beperken van het netwerk, het offline zetten of het blokkeren van één specifieke aanvraag. Doe dit op een testomgeving of op een pagina waar je bezoekers niet schaadt. Test alleen leesaanvragen zoals voorraad of prijs. Bij een aanvraag die iets opslaat kan een fout of time-out optreden nadat de opslag al gelukt is, dus gebruik daar een testomgeving en een unieke, opvraagbare testactie.

1. Open de pagina met de ontwikkelaarstools aan en het tabblad voor netwerkverkeer zichtbaar.
2. Zoek de API-aanvraag en noteer URL, methode en normale statuscode.
3. Blokkeer die ene aanvraag of zet het netwerk offline en herlaad.
4. Kijk wat er op de pagina verschijnt: leeg vlak, spinner die blijft draaien, foutmelding of vervangende inhoud.
5. Herhaal met een trage verbinding om een time-out na te bootsen.

Noteer per scenario wat je ziet. Een browsercontrole toont wat een gewone bezoeker ervaart, niet hoe een zoekmachine de pagina verwerkt.

Een goede foutstaat heeft drie delen: een begrijpelijke melding, een alternatief en een actie. De melding zegt kort dat de informatie nu niet beschikbaar is. Het alternatief is basisinhoud die zonder API werkt, zoals een vaste omschrijving, een telefoonnummer of een link naar contact. De actie is een knop om opnieuw te proberen.

Hou de basisinhoud los van de aanroep: tekst die al in de HTML staat blijft zichtbaar als de aanvraag faalt. Zo blijft de pagina bruikbaar. Toon nooit een leeg element met als enige hint dat er niets staat, en zorg dat de foutstatus zichtbaar is voor bezoekers en hulpmiddelen. Vermijd ook een spinner zonder einde; stel een redelijke wachttijd in waarna de foutstaat verschijnt. Welke wachttijd redelijk is, hangt af van je API en publiek en kan ik niet voor jou bepalen.

Een retry hoort bewust en beperkt te zijn. Laat de bezoeker zelf opnieuw proberen met een knop, of probeer automatisch een klein aantal keren met oplopende pauze. Beperk het aantal pogingen, anders belast je een API die al problemen heeft nog meer. Automatisch of handmatig opnieuw proberen is alleen veilig voor leesaanvragen of acties die idempotent zijn, zodat een herhaling geen dubbele bestelling of boeking veroorzaakt. Na de laatste poging toon je de foutstaat met de handmatige knop.

Gebruik dit beslisblad voor elke API-afhankelijke plek:

Het onderscheid in de laatste rij is belangrijk: een geslaagde aanvraag zonder resultaten is iets anders dan een mislukte aanvraag. Meng die twee niet, anders weet de bezoeker niet of er echt niets is.

Een foutmelding die alleen visueel verschijnt, bereikt niet iedereen. De W3C-handleidingen over toegankelijkheid leggen uit hoe je webinhoud bruikbaar maakt voor mensen met een beperking en tegelijk gebruiksvriendelijker voor iedereen. Test daarom ook zonder muis: bereik je de retry-knop met het toetsenbord, en is de melding in tekst aanwezig in plaats van alleen in een afbeelding of kleur? Of een schermlezer de melding aankondigt, controleer je met je eigen hulpmiddel; ik beloof hier geen specifieke technische implementatie.

Controleer ook het laadgedrag. De cursus Learn Performance van web.dev behandelt hoe resourceloading de laadervaring beïnvloedt. Laad je API-afhankelijk blok niet zo dat het de rest van de pagina vertraagt. Als redactionele suggestie: reserveer plaats voor de foutstaat en controleer in je eigen test of de lay-out verspringt wanneer de melding verschijnt.

Een fictief bedrijf toont op een productpagina 'op voorraad' via een externe API. Invoer voor de test: één productpagina, één API-aanvraag, vier scenario's. Alle waarden hieronder zijn verzonnen.

1. Normaal: de widget toont de voorraadstatus. Noteer de statuscode van de aanvraag.
2. Aanvraag geblokkeerd: verwacht een melding 'voorraad nu niet beschikbaar', de productbeschrijving en prijs blijven zichtbaar, een retry-knop is aanwezig.
3. Trage verbinding: verwacht een foutstaat na de afgesproken wachttijd, geen eindeloze spinner.
4. Geldig antwoord met nul stuks: verwacht de tekst 'uitverkocht', niet de foutmelding.

Zet het resultaat in een korte overdrachtsnotitie: pagina, aanvraag-URL, ingestelde wachttijd, aantal retries en wat je per scenario zag. Wil je daarna ook zien welke zichtbare signalen je site publiek uitstuurt, bekijk ze dan via Marketing Scan. Die scan meet publieke signalen en voert deze foutscenario's niet uit.