Lỗi

Partner API sử dụng mã trạng thái HTTP tiêu chuẩn và nội dung phản hồi JSON để giải thích lý do yêu cầu thất bại.

Cấu trúc phản hồi lỗi

Hầu hết các lỗi API trả về nội dung JSON gồm một thông báo và, khi có, các chi tiết có cấu trúc.

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

Một số endpoint theo lĩnh vực cụ thể trả về trạng thái và lý do rõ ràng. Ví dụ: các lỗi kiểm soát ra vào bao gồm các trường như reason, door_id, facility_id và event_id.

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

Mã trạng thái

400 Bad Request

Yêu cầu sai định dạng hoặc thiếu các trường bắt buộc. Hãy sửa yêu cầu trước khi thử lại.

401 Unauthorized

Xác thực thất bại. Hãy kiểm tra rằng bạn đang sử dụng HTTP Basic Auth với khóa bí mật API làm tên người dùng và mật khẩu để trống.

403 Forbidden

Khóa hợp lệ nhưng thao tác không được phép. Các nguyên nhân phổ biến gồm dùng khóa chỉ đọc cho thao tác ghi hoặc cố truy cập một cơ sở chưa bật tích hợp của bạn.

404 Not Found

Không tìm thấy tài nguyên được yêu cầu hoặc tài nguyên đó không khả dụng với tích hợp của bạn.

409 Conflict

Yêu cầu xung đột với trạng thái hiện tại của tài nguyên. Đối với kiểm soát ra vào, trường hợp này có thể bao gồm việc Door/Gate Controller đang ở chế độ bảo trì.

422 Unprocessable Entity

Yêu cầu là JSON hợp lệ nhưng không vượt qua bước kiểm tra ngữ nghĩa. Hãy sửa dữ liệu trước khi thử lại.

429 Too Many Requests

Tích hợp đã vượt quá giới hạn tốc độ được nêu trong tài liệu. Hãy thử lại với thời gian chờ tăng theo cấp số nhân.

500 Internal Server Error

Performance Hub không thể hoàn tất yêu cầu do lỗi nội bộ. Hãy thử lại với thời gian chờ tăng dần. Nếu sự cố vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ kèm endpoint, dấu thời gian và nội dung phản hồi.

503 Service Unavailable

Một dịch vụ hoặc thiết bị phụ thuộc không khả dụng. Đối với thao tác mở khóa Door/Gate Controller, điều này có thể có nghĩa là bộ điều khiển đang ngoại tuyến.

504 Gateway Timeout

Thao tác đã hết thời gian chờ. Đối với thao tác mở khóa Door/Gate Controller, điều này có nghĩa là việc mở khóa chưa được xác nhận trước khi hết khoảng thời gian chờ.

Lỗi Access Time Window

Bước kiểm tra khung thời gian thất bại trước khi ảnh chụp nhanh không hợp lệ được ghi. Các nguyên nhân phổ biến không thể thử lại gồm:

Thiếu access_time_windows_revision khi có access_time_windows.
Giá trị epoch dạng chuỗi, dạng số thực hoặc có khả năng tính bằng mili giây.
Múi giờ IANA không hợp lệ, khoảng thời gian bị đảo ngược, external_id trùng lặp, các khối hằng tuần chồng lấn hoặc một khối qua đêm chưa được tách.
Giá trị nằm ngoài giới hạn về số lượng, độ dài hoặc khoảng thời gian được nêu trong tài liệu.

Một phiên bản lặp lại với nội dung đã chuẩn hóa khác sẽ trả về 409 Conflict. Hãy đối soát với trạng thái có thẩm quyền mới nhất và cấp một phiên bản mới hơn; không tiếp tục thử lại cặp đang xung đột. Một phiên bản cũ hơn được báo cáo là ảnh chụp nhanh cũ bị bỏ qua thay vì được phép ghi đè trạng thái mới hơn. Một scope_key không xác định hoặc chưa được ánh xạ sẽ không được cấp quyền truy cập và cần được xử lý như một cảnh báo cấu hình.

Nếu việc gửi bị hết thời gian chờ hoặc nhận lỗi 5xx tạm thời, hãy thử lại đúng ảnh chụp nhanh đã chuẩn hóa đó với cùng phiên bản. Nếu việc truy xuất từ nguồn upstream thất bại, hãy bỏ hoàn toàn trường khung thời gian; không bao giờ thay thế bằng một mảng rỗng.

Hướng dẫn thử lại

Thử lại các lỗi sau với thời gian chờ tăng theo cấp số nhân có giới hạn:

429
500
502
503
504

Không thử lại một cách mù quáng đối với các lỗi sau:

400
401
403
404
409
422

Đối với kiểm soát ra vào, luôn coi các phản hồi hết thời gian chờ và ngoại tuyến là lần mở khóa thất bại, trừ khi các quy tắc ra vào và quy trình an toàn của riêng bạn quy định khác.

Thông tin cần cung cấp cho bộ phận hỗ trợ

Khi liên hệ bộ phận hỗ trợ, hãy cung cấp:

Endpoint và phương thức HTTP.
Dấu thời gian và múi giờ.
ID khóa đối tác, không phải khóa bí mật.
Mã định danh cơ sở đã sử dụng.
ID bản ghi nguồn từ hệ thống của bạn.
Trạng thái và nội dung phản hồi.
event_id hoặc command_id nếu có.