Foutafhandeling

De vitalera-gezondheidszorg-API gebruikt standaard HTTP-statuscodes en retourneert gestructureerde foutantwoorden om u te helpen problemen in uw RPM-integratie te diagnosticeren en op te lossen. Of u nu vitale functies verzamelt van medische apparaten of klinische workflows beheert, consistente foutafhandeling zorgt voor betrouwbare gegevensuitwisseling.

Foutantwoordformaat

Alle foutantwoorden volgen een consistente JSON-structuur:

{
  "detail": "A human-readable description of the error.",
  "code": "error_code"
}

Voor validatiefouten bevat het antwoord veldspecifieke details:

{
  "field_name": ["This field is required."],
  "nested_field": {
    "sub_field": ["Ensure this value is greater than 0."]
  }
}

Veelvoorkomende HTTP-statuscodes

Clientfouten (4xx)

Code	Betekenis	Beschrijving
400	Bad Request	De verzoekinhoud is misvormd of er ontbreken vereiste velden. Controleer het antwoord op veldspecifieke validatiefouten.
401	Unauthorized	Authenticatie mislukt. Het JWT-token ontbreekt, is verlopen of ongeldig.
403	Forbidden	De geauthenticeerde gebruiker heeft geen toestemming om toegang te krijgen tot deze resource of deze actie uit te voeren.
404	Not Found	De gevraagde resource bestaat niet, of de gebruiker heeft er geen zichtbaarheid op.
422	Unprocessable Entity	Het verzoek is goed gevormd maar bevat semantische fouten (bijv. ongeldige toestandsovergang, schending van bedrijfsregel).
429	Too Many Requests	Rate limit overschreden. Zie Rate limits voor details over limieten en herhalingsstrategieen.

Serverfouten (5xx)

Code	Betekenis	Beschrijving
500	Internal Server Error	Er is een onverwachte fout opgetreden op de server. Als dit aanhoudt, neem dan contact op met support met het request-ID.
502	Bad Gateway	Een downstream-service is tijdelijk niet beschikbaar. Probeer het na korte vertraging opnieuw.
503	Service Unavailable	De service ondergaat onderhoud. Controleer de statuspagina voor updates.

Authenticatiefouten

Verlopen token

{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid"
}

Oplossing: Vraag een nieuw access token aan met uw refresh token of client credentials. Zie Authenticatie.

Ontbrekend token

{
  "detail": "Authentication credentials were not provided."
}

Oplossing: Voeg een geldig JWT-token toe in de Authorization: Bearer <token>-header.

Validatiefouten

Validatiefouten retourneren 400 Bad Request met veldspecifieke berichten:

{
  "status": ["\"invalid\" is not a valid choice."],
  "effective_period_start": ["This field is required."]
}

Oplossing: Herstel de aangegeven velden en probeer het verzoek opnieuw. Raadpleeg de API-referentie voor geldige veldwaarden.

Rate limit-fouten

Wanneer u de rate limit overschrijdt, retourneert de API 429 Too Many Requests:

{
  "detail": "Request was throttled. Expected available in 30 seconds."
}

Oplossing: Wacht de in het antwoord of in de Retry-After-header aangegeven duur voordat u het opnieuw probeert. Zie Rate limits voor quota-details.

Tips voor probleemoplossing

1. Controleer de antwoordbody -- foutantwoorden bevatten altijd een menselijk leesbaar detail-bericht.
2. Valideer uw JWT -- gebruik jwt.io om uw token te decoderen en de vervaltijd (exp-claim) te controleren.
3. Verifieer machtigingen -- zorg ervoor dat uw applicatie of gebruikersrol toegang heeft tot de gevraagde resource.
4. Controleer het verzoekformaat -- vergelijk uw verzoek met de API-referentievoorbeelden.
5. Controleer rate limits -- als u 429-antwoorden ontvangt, implementeer dan exponentiele backoff.
6. Neem contact op met support -- voor aanhoudende 500-fouten, neem contact op met support@vitalera.io met de verzoektijdstempel en het eindpunt.