Hatalar

Partner API, bir isteğin neden başarısız olduğunu açıklamak için standart HTTP durum kodlarını ve JSON yanıt gövdelerini kullanır.

Hata yanıtı biçimi

Çoğu API hatası, bir mesaj ve varsa yapılandırılmış ayrıntılar içeren bir JSON gövdesi döndürür.

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

Bazı alana özgü uç noktalar açık bir durum ve neden döndürür. Örneğin erişim denetimi hataları reason, door_id, facility_id ve event_id gibi alanlar içerir.

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

Durum kodları

400 Bad Request

İstek hatalı biçimlendirilmiş veya zorunlu alanlar eksik. Yeniden denemeden önce isteği düzeltin.

401 Unauthorized

Kimlik doğrulama başarısız oldu. API gizli anahtarınızı kullanıcı adı olarak ve boş bir parolayla HTTP Basic Auth kullandığınızı kontrol edin.

403 Forbidden

Anahtar geçerli ancak işleme izin verilmiyor. Yaygın nedenler arasında bir yazma işlemi için salt okunur anahtar kullanmak veya entegrasyonunuzun etkin olmadığı bir tesise erişmeye çalışmak bulunur.

404 Not Found

İstenen kaynak bulunamadı veya entegrasyonunuz tarafından kullanılamıyor.

409 Conflict

İstek, kaynağın mevcut durumuyla çakışıyor. Erişim denetimi için bu, bir Door/Gate Controller'ın bakım modunda olmasını içerebilir.

422 Unprocessable Entity

İstek geçerli bir JSON ancak anlamsal doğrulamadan geçemiyor. Yeniden denemeden önce verileri düzeltin.

429 Too Many Requests

Entegrasyon belgelenen hız sınırını aştı. Üstel geri çekilmeyle yeniden deneyin.

500 Internal Server Error

Performance Hub, dahili bir hata nedeniyle isteği tamamlayamadı. Geri çekilmeyle yeniden deneyin. Sorun devam ederse uç nokta, zaman damgası ve yanıt gövdesiyle destekle iletişime geçin.

503 Service Unavailable

Bağımlı bir hizmet veya cihaz kullanılamıyor. Door/Gate Controller kilit açma işlemlerinde bu, kontrol cihazının çevrimdışı olduğu anlamına gelebilir.

504 Gateway Timeout

İşlem zaman aşımına uğradı. Door/Gate Controller kilit açma işlemlerinde bu, kilit açmanın zaman aşımı penceresinden önce onaylanmadığı anlamına gelir.

Access Time Window hataları

Pencere doğrulaması, geçersiz anlık görüntü yazılmadan önce başarısız olur. Yeniden denenemeyen yaygın nedenler şunlardır:

• access_time_windows mevcutken access_time_windows_revision değerinin eksik olması.
• Dize, kayan noktalı veya büyük olasılıkla milisaniye cinsinden epoch değerleri.
• Geçersiz bir IANA saat dilimi, ters çevrilmiş aralık, yinelenen external_id, çakışan haftalık bloklar veya bölünmemiş bir gece bloğu.
• Belgelenen sayı, uzunluk veya kapsam sınırlarının dışında bir değer.

Farklı normalleştirilmiş içerikle yinelenen bir revizyon 409 Conflict hatasıdır. En son yetkili durumla mutabakat sağlayın ve daha yeni bir revizyon atayın; çakışan çifti yeniden denemeye devam etmeyin. Daha eski bir revizyon, daha yeni durumun üzerine yazmasına izin verilmek yerine eski olduğu için atlanan bir anlık görüntü olarak bildirilir. Bilinmeyen veya eşlenmemiş bir scope_key, yetkilendirme açısından kapalı başarısız olur (fail closed) ve bir yapılandırma uyarısı olarak ele alınmalıdır.

Teslimat zaman aşımına uğrarsa veya geçici bir 5xx alırsa tam olarak aynı normalleştirilmiş anlık görüntüyü aynı revizyonla yeniden deneyin. Üst kaynak sorgusu başarısız olduysa pencere alanını tamamen göndermeyin; asla boş bir diziyle değiştirmeyin.

Yeniden deneme yönergeleri

Bunları sınırlı üstel geri çekilmeyle yeniden deneyin:

• 429
• 500
• 502
• 503
• 504

Bunları körü körüne yeniden denemeyin:

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

Erişim denetiminde, kendi erişim kurallarınız ve güvenlik süreçleriniz aksini söylemedikçe zaman aşımı ve çevrimdışı yanıtlarını her zaman başarısız kilit açma olarak değerlendirin.

Eklenecek destek ayrıntıları

Destekle iletişime geçerken şunları ekleyin:

• Uç nokta ve HTTP yöntemi.
• Zaman damgası ve saat dilimi.
• Gizli anahtar değil, iş ortağı anahtar kimliği.
• Kullanılan tesis tanımlayıcısı.
• Sisteminizdeki kaynak kayıt kimliği.
• Yanıt durumu ve gövdesi.
• Varsa event_id veya command_id.