Technische tips & tricks Notificaties

Hoe omgaan met fouten

HTTP 401

Er is geen of geen geldig token in de Authorization Header, zie Beveiliging Notificaties via ACM/IDM . Vraag een token aan met scope dv_notificaties_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 de notificatie aan te maken. Deze rechten worden toegekend door het Aansluitingenteam tijdens het aansluiting proces:

• De applicatie (ACM client) moet gekend zijn als Aanbieder van notificaties

• De Afzender namens wie je notificaties aanmaakt moet gekend zijn als Afzender

• De Aanbieder en Afzender moeten de toestemming hebben om notificaties over het gevraagde product te sturen, via de gevraagde kanalen (passief en/of email)

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

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

Je kan deze notificatie later onveranderd opnieuw aanbieden, als 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",
  "field": "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 belangrijkste error codes:

• 2001: 1 of meer velden van de input zijn niet correct. Voor elk fout veld is er een extra foutomschrijving in de “errors” lijst

• 1071: er bestaat reeds een notificatie met de gegeven id. Als dit gebeurt in code die een retry doet van een potentieel gefaalde POST notificaties, dan betekent dit dat de vorige oproep gelukt is. Deze notificatie is dus geslaagd

• 1094: er mag geen notificatie verstuurt worden want de bestemmeling is minder dan 12 jaar

• 1093: voor bestemmelingen tussen 12 en 18 jaar zijn slechts een beperkt aantal producten toegelaten. De notificatie bevat een product dat niet toegelaten is

In alle gevallen zullen de message en description velden aangeven wat er fout was. Sowieso zal de notificatie niet aanvaard worden met de huidige inhoud.

HTTP 429

De Notificaties 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 3600 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 berichten stuurt, maar omdat andere gebruiker(s) een groot aantal oproepen doen.

Krijg je deze fout frequent, contacteer dan het Notificaties 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 notificaties te versturen. Zie hieronder voor performantie tips.

Performantietips

ACM-token

Als je meerdere notificaties verstuurt, probeer dan zoveel mogelijk één ACM token te hergebruiken. Een ACM token aanmaken en valideren is vaak het traagste deel van een notificatie versturen/verwerken. Notificaties 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 notificaties versturen

Stuur notificaties 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 notificaties. Zie ook de HTTP 429 respons als er teveel notificaties tegelijk aangeboden worden

Een notificatie aanbieden kost meestal minder dan 1-2s. Uitzonderlijk kan het langer duren, door factoren die niet altijd onder controle zijn van de Notificaties bouwsteen, zoals de huidige belasting en de respons tijden van andere systemen die opgeroepen worden door Notificaties. 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 notificatie 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 notificaties in een queue te plaatsen en later opnieuw te proberen. Als je een HTTP 400 response met foutcode 1071 (“Bundel reeds eerder ingevoerd”) krijgt bij een retry, geeft dat aan dat deze notificatie bij de eerdere verzending al verwerkt was. Deze hoeft dus niet opnieuw verzonden te worden.

Notificaties worden vooral opgevraagd tussen 08:00 en 20:00 op werkdagen. Je mag ook op deze drukkere momenten nieuwe notificaties aanbieden. Maar als je een grote batch notificaties (100.000 notificaties of meer) wil aanbieden, raden we aan om dit 's nachts te plannen zodat deze batch sneller verwerkt wordt en alle notificaties 's ochtends klaar staan om gelezen te worden.