Błędy

Partner API używa standardowych kodów stanu HTTP i treści odpowiedzi w formacie JSON, aby wyjaśnić, dlaczego żądanie się nie powiodło.

Struktura odpowiedzi z błędem

Większość błędów API zwraca treść JSON z komunikatem oraz, jeśli są dostępne, szczegółami w formie strukturalnej.

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

Niektóre punkty końcowe specyficzne dla domeny zwracają jawny stan i przyczynę. Na przykład błędy kontroli dostępu zawierają pola takie jak reason, door_id, facility_id i event_id.

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

Kody stanu

400 Bad Request

Żądanie ma nieprawidłowy format lub brakuje w nim wymaganych pól. Popraw żądanie przed ponowieniem.

401 Unauthorized

Uwierzytelnianie nie powiodło się. Sprawdź, czy używasz HTTP Basic Auth z tajnym kluczem API jako nazwą użytkownika i pustym hasłem.

403 Forbidden

Klucz jest prawidłowy, ale operacja jest niedozwolona. Typowe przyczyny to użycie klucza tylko do odczytu w operacji zapisu lub próba dostępu do obiektu, w którym Twoja integracja nie jest włączona.

404 Not Found

Nie znaleziono żądanego zasobu lub nie jest on dostępny dla Twojej integracji.

409 Conflict

Żądanie jest sprzeczne z bieżącym stanem zasobu. W przypadku kontroli dostępu może to oznaczać na przykład, że kontroler drzwi/bramy jest w trybie serwisowym.

422 Unprocessable Entity

Żądanie zawiera prawidłowy JSON, ale nie przechodzi walidacji semantycznej. Popraw dane przed ponowieniem.

429 Too Many Requests

Integracja przekroczyła udokumentowany limit liczby żądań. Ponów próbę z wykładniczym wydłużaniem odstępów.

500 Internal Server Error

Performance Hub nie mógł zrealizować żądania z powodu błędu wewnętrznego. Ponów próbę z wydłużaniem odstępów. Jeśli problem nie ustąpi, skontaktuj się z pomocą techniczną, podając punkt końcowy, znacznik czasu i treść odpowiedzi.

503 Service Unavailable

Zależna usługa lub urządzenie jest niedostępne. W przypadku otwierania kontrolera drzwi/bramy może to oznaczać, że kontroler jest offline.

504 Gateway Timeout

Upłynął limit czasu operacji. W przypadku otwierania kontrolera drzwi/bramy oznacza to, że otwarcie nie zostało potwierdzone przed upływem limitu czasu.

Błędy Access Time Windows

Walidacja okien kończy się niepowodzeniem, zanim nieprawidłowa migawka zostanie zapisana. Typowe przyczyny, w przypadku których ponawianie nie pomoże:

• Brak access_time_windows_revision, gdy obecne jest access_time_windows.
• Wartości epoki w postaci ciągu znaków, liczby zmiennoprzecinkowej lub prawdopodobnie w milisekundach.
• Nieprawidłowa strefa czasowa IANA, odwrócony przedział, zduplikowany external_id, nakładające się bloki tygodniowe lub niepodzielony blok nocny.
• Wartość wykraczająca poza udokumentowane limity liczby, długości lub zakresu.

Powtórzona wersja z inną znormalizowaną zawartością powoduje błąd 409 Conflict. Uzgodnij dane z najnowszym wiarygodnym stanem i przydziel nowszą wersję; nie ponawiaj w kółko konfliktowej pary. Starsza wersja jest zgłaszana jako pominięta nieaktualna migawka i nie może nadpisać nowszego stanu. Nieznany lub niezmapowany scope_key powoduje odmowę autoryzacji i należy go traktować jako alert konfiguracyjny.

Jeśli dostarczenie przekroczy limit czasu lub otrzyma przejściowy błąd 5xx, ponów dokładnie tę samą znormalizowaną migawkę z tą samą wersją. Jeśli pobranie danych ze źródła nie powiodło się, całkowicie pomiń pole okien; nigdy nie zastępuj go pustą tablicą.

Wskazówki dotyczące ponawiania

Te błędy ponawiaj z ograniczonym wykładniczym wydłużaniem odstępów:

• 429
• 500
• 502
• 503
• 504

Tych błędów nie ponawiaj bezrefleksyjnie:

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

W przypadku kontroli dostępu zawsze traktuj odpowiedzi o przekroczeniu limitu czasu i stanie offline jako nieudane otwarcia, chyba że Twoje własne reguły dostępu i procesy bezpieczeństwa stanowią inaczej.

Informacje, które należy przekazać pomocy technicznej

Kontaktując się z pomocą techniczną, podaj:

• Punkt końcowy i metodę HTTP.
• Znacznik czasu i strefę czasową.
• Identyfikator klucza partnera, a nie tajny klucz.
• Użyty identyfikator obiektu.
• Identyfikator rekordu źródłowego z Twojego systemu.
• Stan i treść odpowiedzi.
• event_id lub command_id, jeśli są dostępne.