💡 Technische tips & tricks DOSIS

1 Overzicht foutmeldingen
- 1.1 HTTP 401
- 1.2 HTTP 403
- 1.3 HTTP 400
- 1.4 HTTP 429
- 1.5 Overzicht alle foutmeldingen
2 Performantietips
- 2.1 ACM-Token
- 2.2 Performantie van dossiers of toelatingsupdates versturen

Overzicht foutmeldingen

Foutmeldingen die u ontvangen hebt tijdens het verwerken kunt u terugvinden via de self-service pagina https://prod.notificaties.vlaanderen.be/ of via het antwoord dat u terugkrijgt van het aangesproken endpoint. In dat antwoord krijgt u een beschrijving (“description”) en een detailoverzicht van alle gevonden foutmeldingen (“errors“).

Voorbeeld:

{
"code" : "2001",
"message" : "Validatiefouten",
"description" : "Er heeft zich een foutmelding voorgedaan. Gelieve contact op te nemen met het Notificatie team.",
"errors" : [ { "code" : "1100", "message" : "Maximum lengte voor body overschreden (80 KB).", "description" : "De maximum grootte voor een body is 80 KB.", "field" : "SleutelWaardeParen[0].Waarde" } 
]
}

HTTP 401

Er is geen of geen geldig token in de Authorization Header, zie Toegangsrechten opzetten voor DOSIS. Vraag een token aan met

scope dv_dosis_import
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 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 dossierbron (met Bron-URI en Bron-ID) moet aangemaakt zijn voor de Afzender (= inhoudelijk verantwoordelijke) van de dossier- en toelatingsupdates
De ACM-client van de Aanbieder (= technisch verantwoordelijke) v(an de updates moet de juiste rechten hebben en gekend zijn als Aanbieder voor de bron

De foutboodschap ziet er als volgt uit:

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

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

HTTP 400

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

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

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

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

HTTP 429

De DOSIS-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 1800 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 statusupdates te versturen. Zie ook de Performantietips hieronder.

Overzicht alle foutmeldingen

Onderstaande tabel geeft een overzicht van alle foutcodes die door de DOSIS-API kunnen worden teruggegeven, met per foutcode de bijbehorende omschrijving en eventuele opmerkingen. Gebruik dit overzicht om validatiefouten sneller te herkennen en gericht op te lossen.

Foutcode	Omschrijving	Opmerking

Foutcode	Omschrijving	Opmerking
G_1	VeldIsVerplicht
G_3	GenericVeldWaardeOngeldig
G_4	VeldIsGeenUri
G_2	VeldTeLang
0	BronVereist
1	BronOnbekend
2	DossierNummerVereist
3	NaamTeLang
4	NaamVereist
5	StatusVereist
6	InvalidProduct
7	OntvangstDatumVereist
8	WijzigingsDatumVereist
9	WijzigingsDatumOngeldig
10	StreefDatumOngeldig
11	AgentIdentificatieTeLang
12	AgentIdentificatieOngeldig
13	Minstens1AgentVereist
14	MappingException
15	DossierNummerTeLang
16	IdentificatieVereist
17	BeheerderNaamTeLang
18	BeheerderDienstTeLang
19	BeheerderTelefoonTeLang
20	BeheerderTelefoonOngeldig
21	BeheerderEmailOngeldig
22	BeheerderEmailTeLang
23	BeheerderWebsiteTeLang
24	BeheerderWebsiteOngeldig
25	BeheerderAdresStraatTeLang
26	BeheerderAdresNummerTeLang
27	BeheerderAdresPostcodeTeLang
28	BeheerderAdresGemeenteTeLang
29	StatusDetail1TeLang
29a	StatusDetail1Required
30	StatusDetail2TeLang
30a	StatusDetail2Required
31	StatusActieTeLang
32	ExtraInformatieTeLang
33	DoorverwijzingTeLang
34	DoorverwijzingOngeldig
35	AgentIdentificatieVereist
36	AgentToegangsRechtCodeVereist
37	AgentToegangsRechtCodeTeLang
38	ActieNodigVereist
39	ActieVereist
40	ActieNietVereist
41	KanStatusNietMappen
42	LaatsteDeelBetalingDatumOngeldig
43	LaatsteDeelBetalingDatumVereist
44	Minstens1ToegangsRechtVereist
45	Minstens1ProductVereist
49	BronUriMoetUriZijn
51	AfzenderVerplicht	Old error code only here to remind us of what the last error code that was used was
52	BronUriVereist
53	OrganisatieIdVereist
54	AfzenderOrganisatieCodeVereist
55	OmschrijvingVereist
56	BronOntoegankelijk
57	AfzenderOrganisatieNaamVereist
58	BronUriMoetUniekZijn
59	BronProductFaseBestaatReeds
60	OngeldigRijksregisternummer
61	OngeldigOndernemingsnummer
62	DetailStatusTeLang
63	ProductBestaatReeds
64	ProductOnbekend
72	DatumOngeldig
73	InvalidTypeDossier
74	InvalidOutputType
75	InvalidDocumentatie
76	Maximaal1ProductIsToegestaan
77	OngeldigVerenigingsnummer
78	BronUriToegangGeweigerd	Access control based on Bron Uri. Should replace BronOntoegankelijk (56)
79	BronIdToegangGeweigerd	Access control based on Bron Id. Should replace BronOntoegankelijk (56)
80	BronOnbestaandToegangGeweigerd	Access control based on available bronnen finds no configured bronnen. Should replace BronOntoegankelijk (56)
81	OrganisatieCodeEnOrganisatieIdMismatch	Er moet een strikte overeenkomst zijn tussen (GeoSecure) organisatieId en afzender organisatie code (OVO code)
82	AfzenderOrganisatieCodeMoetOvoCodeZijn
83	AfzenderOrganisatieNaamTeLang
84	OrganisatieReedsGebruiktInDossier
85	ReferentieVereist
86	ToelatingReferentieLengteOngeldig
87	BronIdVereist
88	KanalenVereist
89	KanaalTypeVereist
90	KanaalTypeOngeldig
91	AanbiederOrganisatieNaamVerplicht
92	AanbiederOrganisatieCodeOfOndernemingsNummerVerplicht
93	AanbiederMetIdNietGevonden
94	AgentJongerDan12
95	AgentJongerDan18
96	Translations
NotFound	DossierByBronUriAndDossierNummerNotFound
2001	ValidatieFoutenErrorCode
5106	ForbiddenAccessErrorCode

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. DOSIS 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 dossiers of toelatingsupdates versturen

Stuur updates 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 update aanbieden kost meestal minder dan 1 of 2 seconden. Uitzonderlijk duurt het langer door factoren buiten de DOSIS-bouwsteen om, zoals de belasting en de responstijden van andere systemen die worden opgeroepen door DOSIS. 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.

Documentatie bouwstenen digitale loketten