Technische tips & tricks DOSIS

Hoe omgaan met fouten

HTTP 401

Er is geen of geen geldig token in de Authorization Header, zie Beveiliging DOSIS via ACM/IDM . Vraag een token aan met scope dv_dosis_import en de juiste “audience” voor de omgeving. Ziehttps://authenticatie.vlaanderen.be/docs/beveiligen-van-api/oauth-rest/rest-server2server/aanvraag-access-token/

Deze fout komt soms voor omdat eenzelfde token te lang gebruikt wordt. Zie onder bij de ACM token performantie tips.

HTTP 403

Deze fout geeft aan dat je ACM client niet de nodige rechten heeft om het dossier of de toelating aan te passen. Deze rechten worden toegekend door het Aansluitingenteam tijdens het aansluiting proces:

• De Dossier Bron (met Bron Uri en Bron Id) moet aangemaakt zijn voor de Afzender (= inhoudelijk verantwoordelijke) van de dossier en toelating updates

• De ACM client van de Aanbieder (= technisch verantwoordelijke) van de updates moet de juiste rechten hebben en gekend zijn als Aanbieder voor de bron

De foutboodschap die je terugkrijgt ziet er als volgt uit en zal duidelijker aangeven wat er fout ging

{
  "code": "string",
  "message": "string",
  "description": "string"
}

Je kan deze update later onveranderd opnieuw aanbieden, zodra de aansluitingsgegevens aangepast zijn.

HTTP 400

De inhoud van de notificatie voldoet niet aan de vereisten. De respons die je terugkrijgt is

{
  "code": "string",
  "message": "string",
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "description": "string",
      "field": "string"
    }
  ]
}

Nota: het “errors” veld is optioneel en enkel aanwezig als er meer gedetailleerde validatie boodschappen zijn.

De message en description velden geven aan wat er fout was. Sowieso zal de dossier of toelating update niet aanvaard worden met de huidige inhoud.

HTTP 429

De DOSIS API wordt beschermd door een Application Firewall. Indien er teveel calls tegelijk komen, dan krijg je een error 429 “Too many requests.” Als je deze fout krijgt, open dan je “Circuitbreaker” en probeer later opnieuw.

De huidige limiet is 1800 oproepen per minuut. Let wel: dit is een globale limiet, voor alle gebruikers van de API. Het is dus mogelijk dat je een 429 fout krijgt, niet omdat je zelf te snel de API oproept, maar omdat andere gebruiker(s) een groot aantal oproepen doen.

Krijg je deze fout frequent, contacteer dan het DOSIS team of breng het onderwerp op op het wekelijks “Technisch Spreekuur”. Mogelijk moet de limiet verhoogd worden of is er een betere aanpak om grote aantallen status updates te versturen. Zie hieronder voor performantie tips.

Performantie tips

ACM Token

Als je meerdere updates verstuurt, probeer dan zoveel mogelijk één ACM token te hergebruiken. Een ACM token aanmaken en valideren is vaak het traagste deel van een update versturen/verwerken. DOSIS valideert een ACM token slechts 1 maal, bij de eerste oproep met dat token. Daarna wordt de validatie gecached en zijn alle volgende oproepen met dat token een stuk sneller.

Als je een token ontvangt van ACM, bevat de respons een “expires_in” veld dat aangeeft hoelang het token nog geldig is. Gebruik het token niet tot het laatste moment, want dan kan het voorkomen dat het token, tussen het moment dat het opgestuurd wordt en het gevalideerd wordt, ongeldig wordt. Je krijgt dan af en toe onverwachte HTTP 401 responses. Een nieuw token is meestal een uur geldig. Vraag een nieuw token aan als de resterende geldigheidsduur minder dan 1 minuut is. Zo ben je zeker dat het token geldig is voor de hele duurtijd van de volgende oproep.

Performantie van dossier of toelating updates versturen

Stuur updates bij voorkeur sequentieel op:

• als de API wat trager is door hoge belasting, dan stuur je ook wat trager notificaties door

• als een token moet gevalideerd worden, dan zijn alle andere oproepen met hetzelfde token geblokkeerd tot het resultaat van de validatie gekend is

• je deelt de bandbreedte en verwerkingskracht met alle andere aanbieders van DOSIS. Zie ook de HTTP 429 respons als er teveel notificaties tegelijk aangeboden worden

Een update aanbieden kost meestal minder dan 1-2s. Uitzonderlijk kan het langer duren, door factoren die niet altijd onder controle zijn van de DOSIS bouwsteen, zoals de huidige belasting en de respons tijden van andere systemen die opgeroepen worden door DOSIS. Gebruik een communicatie timeout die voldoende lang is om met dergelijke schommelingen om te kunnen. Typisch is een timeout van 15-30s.

Wees klaar om een update opnieuw te versturen indien het de eerste keer niet lukt omdat er een fout, timeout of 429 respons komt. Dit kan bvb door deze gefaalde updates in een queue te plaatsen en later opnieuw te proberen.

Bij een HTTP 400 validatiefout respons heeft het geen zin om opnieuw te proberen zonder de inhoud aan te passen. Let wel:

• POST /api/v1/dosis/dossiers doet de validatie asynchroon. Gebruik GET /api/v2/dosis/resultaten/fouten om eventuele validatie fouten later op te vragen.

• gebruik liever POST /api/v2/dosis/dossiers want deze API geeft meteen alle validatiefouten terug, vóór het dossier in de achtergrond verwerkt wordt.