ข้อผิดพลาด

Partner API ใช้รหัสสถานะ HTTP มาตรฐานและเนื้อหาการตอบกลับแบบ JSON เพื่ออธิบายสาเหตุที่คำขอล้มเหลว

รูปแบบการตอบกลับข้อผิดพลาด

ข้อผิดพลาดของ API ส่วนใหญ่จะส่งคืนเนื้อหา JSON ที่มีข้อความ และรายละเอียดแบบมีโครงสร้างหากมี

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

ปลายทางเฉพาะโดเมนบางรายการจะส่งคืนสถานะและเหตุผลอย่างชัดเจน ตัวอย่างเช่น ความล้มเหลวของการควบคุมการเข้าถึงจะมีฟิลด์ต่าง ๆ เช่น reason, door_id, facility_id และ event_id

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

รหัสสถานะ

400 Bad Request

คำขอมีรูปแบบไม่ถูกต้องหรือไม่มีฟิลด์ที่จำเป็น แก้ไขคำขอก่อนลองใหม่

401 Unauthorized

การยืนยันตัวตนล้มเหลว ตรวจสอบว่าคุณใช้ HTTP Basic Auth โดยใช้คีย์ลับของ API เป็นชื่อผู้ใช้และเว้นรหัสผ่านว่างไว้

403 Forbidden

คีย์ถูกต้องแต่ไม่อนุญาตให้ดำเนินการนี้ สาเหตุที่พบบ่อย ได้แก่ การใช้คีย์แบบอ่านอย่างเดียวสำหรับการดำเนินการเขียน หรือการพยายามเข้าถึงสถานที่ที่ไม่ได้เปิดใช้การผสานรวมของคุณ

404 Not Found

ไม่พบทรัพยากรที่ร้องขอ หรือทรัพยากรนั้นไม่พร้อมให้การผสานรวมของคุณใช้งาน

409 Conflict

คำขอขัดแย้งกับสถานะปัจจุบันของทรัพยากร สำหรับการควบคุมการเข้าถึง อาจรวมถึงกรณีที่ Door/Gate Controller อยู่ในโหมดบำรุงรักษา

422 Unprocessable Entity

คำขอเป็น JSON ที่ถูกต้องแต่ไม่ผ่านการตรวจสอบความถูกต้องเชิงความหมาย แก้ไขข้อมูลก่อนลองใหม่

429 Too Many Requests

การผสานรวมเกินขีดจำกัดอัตราการเรียกใช้ที่ระบุไว้ในเอกสาร ลองใหม่โดยใช้การเว้นระยะแบบเอ็กซ์โพเนนเชียล

500 Internal Server Error

Performance Hub ไม่สามารถดำเนินการตามคำขอได้เนื่องจากข้อผิดพลาดภายใน ลองใหม่โดยเว้นระยะ หากปัญหายังคงอยู่ ให้ติดต่อฝ่ายสนับสนุนพร้อมระบุปลายทาง การประทับเวลา และเนื้อหาการตอบกลับ

503 Service Unavailable

บริการหรืออุปกรณ์ที่เกี่ยวข้องไม่พร้อมใช้งาน สำหรับการปลดล็อก Door/Gate Controller อาจหมายความว่าตัวควบคุมออฟไลน์

504 Gateway Timeout

การดำเนินการหมดเวลา สำหรับการปลดล็อก Door/Gate Controller หมายความว่าการปลดล็อกไม่ได้รับการยืนยันก่อนหมดช่วงเวลาที่กำหนด

ความล้มเหลวของ Access Time Window

การตรวจสอบความถูกต้องของช่วงเวลาจะล้มเหลวก่อนที่สแนปช็อตที่ไม่ถูกต้องจะถูกเขียน สาเหตุที่พบบ่อยซึ่งลองใหม่ไม่ได้ ได้แก่:

ไม่มี access_time_windows_revision เมื่อมี access_time_windows
ค่า epoch ที่เป็นสตริง ทศนิยม หรือมีแนวโน้มว่าเป็นมิลลิวินาที
เขตเวลา IANA ที่ไม่ถูกต้อง ช่วงเวลาที่กลับด้าน external_id ซ้ำ บล็อกรายสัปดาห์ที่ทับซ้อนกัน หรือบล็อกข้ามคืนที่ไม่ได้แยกออก
ค่าที่อยู่นอกขีดจำกัดด้านจำนวน ความยาว หรือช่วงเวลาที่ระบุไว้ในเอกสาร

เวอร์ชันซ้ำที่มีเนื้อหาที่ปรับให้เป็นมาตรฐานแล้วแตกต่างกันจะเป็น 409 Conflict ให้กระทบยอดกับสถานะล่าสุดที่เชื่อถือได้และจัดสรรเวอร์ชันที่ใหม่กว่า อย่าลองส่งคู่ที่ขัดแย้งกันซ้ำ เวอร์ชันที่เก่ากว่าจะถูกรายงานเป็นสแนปช็อตเก่าที่ถูกข้าม แทนที่จะได้รับอนุญาตให้เขียนทับสถานะที่ใหม่กว่า scope_key ที่ไม่รู้จักหรือไม่ได้จับคู่ไว้จะไม่ให้สิทธิ์เข้าถึง สำหรับการให้สิทธิ์ และควรถือเป็นการแจ้งเตือนด้านการกำหนดค่า

หากการส่งหมดเวลาหรือได้รับ 5xx ชั่วคราว ให้ลองส่งสแนปช็อตที่ปรับให้เป็นมาตรฐานเดิมทุกประการซ้ำด้วยเวอร์ชันเดิม หากการดึงข้อมูลจากต้นทางล้มเหลว ให้เว้นฟิลด์ช่วงเวลาไว้ทั้งหมด อย่าแทนที่ด้วยอาร์เรย์ว่างเด็ดขาด

คำแนะนำในการลองใหม่

ลองใหม่สำหรับกรณีต่อไปนี้ด้วยการเว้นระยะแบบเอ็กซ์โพเนนเชียลที่จำกัดจำนวนครั้ง:

429
500
502
503
504

อย่าลองใหม่โดยไม่ไตร่ตรองสำหรับกรณีต่อไปนี้:

400
401
403
404
409
422

สำหรับการควบคุมการเข้าถึง ให้ถือว่าการตอบกลับที่หมดเวลาและออฟไลน์เป็นการปลดล็อกที่ล้มเหลวเสมอ เว้นแต่กฎการเข้าถึงและกระบวนการด้านความปลอดภัยของคุณเองจะระบุไว้เป็นอย่างอื่น

รายละเอียดที่ควรระบุเมื่อติดต่อฝ่ายสนับสนุน

เมื่อติดต่อฝ่ายสนับสนุน ให้ระบุ:

ปลายทางและเมธอด HTTP
การประทับเวลาและเขตเวลา
ID ของคีย์พาร์ทเนอร์ ไม่ใช่คีย์ลับ
ตัวระบุสถานที่ที่ใช้
ID ของเรคคอร์ดต้นทางจากระบบของคุณ
สถานะและเนื้อหาของการตอบกลับ
event_id หรือ command_id หากมี