Fouten

De Partner API gebruikt standaard HTTP-statuscodes en JSON-response-bodies om uit te leggen waarom een verzoek is mislukt.

Structuur van foutresponses

De meeste API-fouten retourneren een JSON-body met een bericht en, waar beschikbaar, gestructureerde details.

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

Sommige domeinspecifieke endpoints retourneren een expliciete status en reden. Fouten bij toegangsbeheer bevatten bijvoorbeeld velden zoals reason, door_id, facility_id en event_id.

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

Statuscodes

400 Bad Request

Het verzoek is onjuist opgebouwd of verplichte velden ontbreken. Corrigeer het verzoek voordat je het opnieuw probeert.

401 Unauthorized

Authenticatie is mislukt. Controleer of je HTTP Basic Auth gebruikt met je geheime API-sleutel als gebruikersnaam en een leeg wachtwoord.

403 Forbidden

De sleutel is geldig, maar de bewerking is niet toegestaan. Veelvoorkomende oorzaken zijn het gebruik van een read-only sleutel voor een schrijfbewerking of een poging om een faciliteit te benaderen waarvoor je integratie niet is ingeschakeld.

404 Not Found

De gevraagde resource is niet gevonden of is niet beschikbaar voor je integratie.

409 Conflict

Het verzoek is in strijd met de huidige status van de resource. Bij toegangsbeheer kan dit betekenen dat een Door/Gate Controller in de onderhoudsmodus staat.

422 Unprocessable Entity

Het verzoek is geldige JSON, maar voldoet niet aan de semantische validatie. Corrigeer de gegevens voordat je het opnieuw probeert.

429 Too Many Requests

De integratie heeft de gedocumenteerde snelheidslimiet overschreden. Probeer het opnieuw met exponentiële backoff.

500 Internal Server Error

Performance Hub kon het verzoek niet voltooien door een interne fout. Probeer het opnieuw met backoff. Blijft het probleem bestaan, neem dan contact op met ondersteuning en vermeld het endpoint, de tijdstempel en de response-body.

503 Service Unavailable

Een afhankelijke service of een apparaat is niet beschikbaar. Bij ontgrendelingen van een Door/Gate Controller kan dit betekenen dat de controller offline is.

504 Gateway Timeout

Er is een time-out opgetreden bij de bewerking. Bij ontgrendelingen van een Door/Gate Controller betekent dit dat de ontgrendeling niet binnen de time-outperiode is bevestigd.

Fouten bij Access Time Windows

De validatie van vensters mislukt voordat de ongeldige momentopname wordt weggeschreven. Veelvoorkomende oorzaken waarbij een nieuwe poging geen zin heeft:

• access_time_windows_revision ontbreekt terwijl access_time_windows aanwezig is.
• Epochwaarden als tekenreeks, als drijvendekommagetal of vermoedelijk in milliseconden.
• Een ongeldige IANA-tijdzone, een omgekeerd interval, een dubbele external_id, overlappende wekelijkse blokken of een nachtelijk blok dat niet is gesplitst.
• Een waarde buiten de gedocumenteerde limieten voor aantal, lengte of tijdsspanne.

Een herhaalde revisie met andere genormaliseerde inhoud levert een 409 Conflict op. Stem af op de meest recente gezaghebbende status en ken een nieuwere revisie toe; blijf het conflicterende paar niet opnieuw proberen. Een oudere revisie wordt gemeld als een verouderde, overgeslagen momentopname en mag een nieuwere status niet overschrijven. Een onbekende of niet-toegewezen scope_key leidt bij autorisatie tot weigering (fail-closed) en moet worden behandeld als een configuratiewaarschuwing.

Als de levering een time-out krijgt of een tijdelijke 5xx ontvangt, probeer dan exact dezelfde genormaliseerde momentopname opnieuw met dezelfde revisie. Als het ophalen bij de upstream bron is mislukt, laat het vensterveld dan helemaal weg; vervang het nooit door een lege array.

Richtlijnen voor nieuwe pogingen

Probeer deze opnieuw met begrensde exponentiële backoff:

• 429
• 500
• 502
• 503
• 504

Probeer deze niet blindelings opnieuw:

• 400
• 401
• 403
• 404
• 409
• 422

Behandel bij toegangsbeheer time-out- en offline-responses altijd als mislukte ontgrendelingen, tenzij je eigen toegangsregels en veiligheidsprocessen anders voorschrijven.

Gegevens voor ondersteuning

Vermeld het volgende wanneer je contact opneemt met ondersteuning:

• Endpoint en HTTP-methode.
• Tijdstempel en tijdzone.
• Partnersleutel-ID, niet de geheime sleutel.
• Gebruikte faciliteitidentificatie.
• Bronrecord-ID uit je systeem.
• Status en body van de response.
• event_id of command_id, indien beschikbaar.