Fehler

Die Partner API verwendet Standard-HTTP-Statuscodes und JSON-Antworttexte, um zu erklären, warum eine Anfrage fehlgeschlagen ist.

Aufbau der Fehlerantwort

Die meisten API-Fehler geben einen JSON-Body mit einer Meldung und, sofern verfügbar, strukturierten Details zurück.

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

Einige domänenspezifische Endpunkte geben einen expliziten Status und Grund zurück. Fehler bei der Zutrittskontrolle enthalten beispielsweise Felder wie reason, door_id, facility_id und 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

Die Anfrage ist fehlerhaft oder es fehlen erforderliche Felder. Korrigieren Sie die Anfrage, bevor Sie sie wiederholen.

401 Unauthorized

Die Authentifizierung ist fehlgeschlagen. Prüfen Sie, ob Sie HTTP Basic Auth mit Ihrem geheimen API-Schlüssel als Benutzernamen und einem leeren Passwort verwenden.

403 Forbidden

Der Schlüssel ist gültig, aber der Vorgang ist nicht zulässig. Häufige Ursachen sind die Verwendung eines schreibgeschützten Schlüssels für einen Schreibvorgang oder der Versuch, auf eine Einrichtung zuzugreifen, für die Ihre Integration nicht aktiviert ist.

404 Not Found

Die angeforderte Ressource wurde nicht gefunden oder ist für Ihre Integration nicht verfügbar.

409 Conflict

Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource. Bei der Zutrittskontrolle kann dies bedeuten, dass sich ein Door/Gate Controller im Wartungsmodus befindet.

422 Unprocessable Entity

Die Anfrage ist gültiges JSON, besteht aber die semantische Validierung nicht. Korrigieren Sie die Daten, bevor Sie die Anfrage wiederholen.

429 Too Many Requests

Die Integration hat die dokumentierte Ratenbegrenzung überschritten. Wiederholen Sie die Anfrage mit exponentiellem Backoff.

500 Internal Server Error

Der Performance Hub konnte die Anfrage aufgrund eines internen Fehlers nicht abschließen. Wiederholen Sie sie mit Backoff. Wenn das Problem weiterhin besteht, wenden Sie sich mit Endpunkt, Zeitstempel und Antworttext an den Support.

503 Service Unavailable

Ein abhängiger Dienst oder ein Gerät ist nicht verfügbar. Bei Entriegelungen über den Door/Gate Controller kann dies bedeuten, dass der Controller offline ist.

504 Gateway Timeout

Bei dem Vorgang ist eine Zeitüberschreitung aufgetreten. Bei Entriegelungen über den Door/Gate Controller bedeutet dies, dass die Entriegelung nicht vor Ablauf des Zeitlimits bestätigt wurde.

Fehler bei Access Time Windows

Die Validierung der Zeitfenster schlägt fehl, bevor der ungültige Snapshot geschrieben wird. Häufige Ursachen, bei denen eine Wiederholung nicht hilft, sind:

• Fehlende access_time_windows_revision, wenn access_time_windows vorhanden ist.
• Epoch-Werte als String, als Gleitkommazahl oder vermutlich in Millisekunden.
• Eine ungültige IANA-Zeitzone, ein umgekehrtes Intervall, eine doppelte external_id, sich überschneidende wöchentliche Blöcke oder ein nicht aufgeteilter Block über Mitternacht.
• Ein Wert außerhalb der dokumentierten Grenzen für Anzahl, Länge oder Zeitspanne.

Eine wiederholte Revision mit abweichendem normalisiertem Inhalt führt zu 409 Conflict. Gleichen Sie mit dem neuesten maßgeblichen Zustand ab und vergeben Sie eine neuere Revision; wiederholen Sie das widersprüchliche Paar nicht immer wieder. Eine ältere Revision wird als veralteter, übersprungener Snapshot gemeldet, statt einen neueren Zustand überschreiben zu dürfen. Ein unbekannter oder nicht zugeordneter scope_key führt bei der Autorisierung zur Verweigerung (fail closed) und sollte als Konfigurationswarnung behandelt werden.

Wenn bei der Zustellung eine Zeitüberschreitung auftritt oder ein vorübergehender 5xx-Fehler zurückkommt, wiederholen Sie genau denselben normalisierten Snapshot mit derselben Revision. Wenn der Abruf aus der Quelle fehlgeschlagen ist, lassen Sie das Zeitfensterfeld vollständig weg; ersetzen Sie es niemals durch ein leeres Array.

Hinweise zu Wiederholungen

Wiederholen Sie diese mit begrenztem exponentiellem Backoff:

• 429
• 500
• 502
• 503
• 504

Wiederholen Sie diese nicht ungeprüft:

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

Behandeln Sie bei der Zutrittskontrolle Zeitüberschreitungs- und Offline-Antworten immer als fehlgeschlagene Entriegelungen, sofern Ihre eigenen Zutrittsregeln und Sicherheitsprozesse nichts anderes vorsehen.

Angaben für den Support

Wenn Sie sich an den Support wenden, geben Sie Folgendes an:

• Endpunkt und HTTP-Methode.
• Zeitstempel und Zeitzone.
• Partner-Schlüssel-ID, nicht den geheimen Schlüssel.
• Verwendete Einrichtungskennung.
• Quelldatensatz-ID aus Ihrem System.
• Antwortstatus und Antworttext.
• event_id oder command_id, sofern verfügbar.