Technische tips & tricks Notificaties

1 Overzicht foutmeldingen
- 1.1 HTTP 401
- 1.2 HTTP 403
- 1.3 HTTP 400
- 1.4 HTTP 429
2 Performantietips
- 2.1 ACM-token
- 2.2 Performantie van notificaties versturen

Overzicht foutmeldingen

HTTP 401

Er is geen of geen geldig token in de Authorization Header, zie Beveiliging Notificaties via ACM/IDM. Vraag een token aan met

dv_notificaties_import
de juiste audience voor de omgeving, zieAanvraag API Access Token

Deze fout komt soms voor omdat eenzelfde token te lang gebruikt wordt. Zie ook Performantietips.

HTTP 403

De ACM-client heeft niet de nodige rechten om het dossier of de toelating aan te passen. Deze rechten worden toegekend door het Aansluitingen-team tijdens het aansluitingsproces.:

De applicatie (ACM-client) moet gekend zijn als Aanbieder van notificaties
De Afzender - namens wie u 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 ziet er als volgt uit:

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

Zodra de aansluitingsgegevens aangepast zijn, kan deze update onveranderd opnieuw worden aangeboden.

HTTP 400

De inhoud van de notificatie voldoet niet aan de vereisten. De respons ziet er als volgt uit:

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

De message- en description-velden geven aan wat er fout was. De notificatie-update wordt niet aanvaard met de huidige inhoud.

Errors is optioneel en enkel aanwezig als er meer gedetailleerde validatieboodschappen zijn.

Dit zijn de belangrijkste foutcodes:

1071: de notificatie met dit ID bestaat al. Gebeurt dit in code die een retry doet van een mogelijks gefaalde POST-notificatie, dan betekent dit dat de vorige oproep gelukt is. Deze notificatie is dus geslaagd.
1093: de notificatie bevat een product dat niet is toegelaten voor bestemmelingen tussen 12 en 18 jaar
1094: de notificatie mag niet worden verstuurd omdat de bestemmeling jonger is dan 12 jaar
2001: 1 of meer inputvelden zijn niet correct. De errors-lijst bevat een extra foutomschrijving voor elk fout veld

HTTP 429

De Notificaties-API wordt beschermd door een Application Firewall. Zodra er te veel calls tegelijk komen, geeft dit de foutboodschap HTTP 429 - Too many requests. Open uw Circuitbreaker en probeer het later opnieuw.

De huidige limiet is 3600 oproepen per minuut voor alle gebruikers van de API. Het is dus ook mogelijk dat u deze fout ziet omdat andere gebruiker(s) een groot aantal oproepen doen.

Krijgt u deze fout frequent, neem contact op met de Servicedesk of kom langs op het technisch spreekuur, wekelijks op dinsdag van 13:00 tot 14:00 uur. De limiet moet misschien verhoogd worden of er bestaat een betere aanpak om grote aantallen notificaties te versturen. Zie ook de Performantietips hieronder.

Performantietips

ACM-token

Wanneer u meerdere updates verstuurt, hergebruik zoveel mogelijk één ACM-token.

Een ACM-token aanmaken en valideren is vaak het traagste deel van een update versturen/verwerken. Notificaties valideert een ACM-token slechts één keer, bij de eerste oproep met dat token. Daarna wordt de validatie gecachet en zijn alle volgende oproepen met datzelfde token een stuk sneller.

Wanneer u 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 omdat het ongeldig wordt tussen het moment dat het wordt opgestuurd en gevalideerd wordt. Dat leidt af en toe tot onverwachte HTTP 401 responses.
Een nieuw token is meestal een uur geldig. Vraag een nieuw token aan wanneer de resterende geldigheidsduur minder dan 1 minuut is. Zo bent u zeker dat het token geldig blijft voor de hele duurtijd van de volgende oproep.

Performantie van notificaties versturen

Stuur notificaties bij voorkeur sequentieel wanneer:

de API trager is door hoge belasting, dan stuurt u ook trager updates door
een token gevalideerd moet worden, dan zijn alle andere oproepen met hetzelfde token geblokkeerd tot het resultaat van de validatie gekend is
u de bandbreedte en de verwerkingskracht deelt met alle andere aanbieders van DOSIS. Zie ook HTTP 429 respons

Een notificatie aanbieden kost meestal minder dan 1 of 2 seconden. Uitzonderlijk duurt het langer door factoren buiten de Notificaties-bouwsteen om, zoals de belasting en de responstijden van andere systemen die worden opgeroepen door Notificaties. Gebruik een communicatietime-out die voldoende lang is om met dergelijke schommelingen om te kunnen. Dit is typisch een time-out van 15 tot 30 seconden.

Stuur een notificatie opnieuw als het de eerste keer niet lukt omdat er een fout, time-out of HTTP 429 respons komt. Dit kan bijv. door de gefaalde notificaties in een queue te plaatsen en later opnieuw te proberen.

Een HTTP 400-validatiefout met foutcode 1071 (“Bundel reeds eerder ingevoerd”) na een retry, betekent dat de notificatie bij de eerdere verzending al werd verwerkt. Het heeft dus geen zin om die notificatie opnieuw te verzenden.

Notificaties worden vooral opgevraagd tussen 08:00 en 20:00 uur op werkdagen. U kunt ook op deze drukkere momenten nieuwe notificaties aanbieden.

Het is aangeraden om grote batchnotificaties (100.000 notificaties of meer) 's nachts te plannen zodat de batch sneller verwerkt wordt en alle notificaties 's ochtends klaar staan om gelezen te worden.

Documentatie voor partners en klanten van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers