Error Handling

De Avallo REST API gebruikt HTTP-statuscodes om aan te geven of een request succesvol is verwerkt.

Foutresponses gebruiken waar mogelijk het mediatype:

application/problem+json

Gebruik de HTTP-statuscode als primaire indicatie van het fouttype. Teksten in title en detail zijn bedoeld voor diagnostiek en kunnen veranderen.

Statuscodes

Het endpoint voor grondwaterstanden kan de volgende statuscodes retourneren:

Statuscode	Betekenis
400 Bad Request	Het request bevat ongeldige parameters of waarden.
401 Unauthorized	De API-sleutel ontbreekt of is ongeldig.
403 Forbidden	De API-sleutel is geldig, maar geeft geen toegang tot de gevraagde gegevens.
404 Not Found	De gevraagde resource is niet gevonden.
405 Method Not Allowed	De gebruikte HTTP-methode wordt niet ondersteund.
429 Too Many Requests	De client moet tijdelijk vertragen.
500 Internal Server Error	Er is een onverwachte fout aan de serverzijde opgetreden.

Problem Details

Een foutresponse kan de volgende velden bevatten:

Veld	Beschrijving
type	Identificatie van het fouttype.
title	Korte omschrijving van het fouttype.
status	De HTTP-statuscode.
detail	Aanvullende informatie over deze specifieke fout.
instance	Verwijzing naar het request waarop de fout betrekking heeft.

Voorbeeld:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "instance": "/v1/groundwater-monitoring-tubes/00000000-0000-0000-0000-000000000000/measurements"
}

Validatiefouten

Bij 400 Bad Request kan de response een aanvullend veld errors bevatten. Dit veld groepeert één of meerdere validatiefouten per parameter.

{
  "type": "about:blank",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "from": [
      "The from value must be a valid date and time."
    ],
    "to": [
      "The to value must be later than from."
    ]
  }
}

Corrigeer het request voordat je het opnieuw uitvoert.

Authenticatie en niet-toegankelijke resources

Een 401 Unauthorized betekent dat de request niet geldig is geauthenticeerd. Controleer of X-API-Key aanwezig is en de juiste API-key bevat.

Voor een peilbuis maakt de API bewust geen onderscheid tussen:

• een onbekende tubeIdentifier;
• een bestaande peilbuis waartoe de API-client geen toegang heeft.

Beide situaties retourneren:

404 Not Found

Hierdoor kan een client niet op basis van de foutresponse vaststellen welke niet-toegankelijke peilbuizen bestaan.

Gebruik GET /v1/groundwater-monitoring-wells om de peilbuisidentifiers op te halen die voor de API-client beschikbaar zijn.

Ongeldig tijdsinterval

Voor het measurements-endpoint zijn from en to verplicht.

De API retourneert 400 Bad Request wanneer bijvoorbeeld:

• from ontbreekt;
• to ontbreekt;
• to niet later is dan from;
• het gevraagde interval groter is dan 366 dagen;
• een datum- of tijdwaarde niet aan het vereiste formaat voldoet.

Opnieuw proberen

Herhaal requests met een 400, 401, 403, 404 of 405 niet automatisch zonder eerst de oorzaak te corrigeren.

Bij 429 Too Many Requests moet de client eerst wachten. Bij een 500 Internal Server Error kan een GET-request beperkt opnieuw worden geprobeerd. Gebruik altijd een maximumaantal pogingen of een totale time-out.

Zie Rate Limiting voor de verwerking van 429-responses.

Probleem melden

Neem contact op met Avallo wanneer een fout blijft optreden nadat de request, authenticatie en autorisatie zijn gecontroleerd. Vermeld het tijdstip, endpointpad, de HTTP-statuscode, API-Version en de ontvangen foutresponse.

Deel nooit de API-key.