Logo Performance HubPerformance Hub
Bahagian laman: Sumber Pembangun & Rakan Kongsi

Ralat

Partner API menggunakan kod status HTTP standard dan badan respons JSON untuk menerangkan sebab permintaan gagal.

Bentuk respons ralat

Kebanyakan ralat API mengembalikan badan JSON dengan mesej dan, jika ada, butiran berstruktur.

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

Sesetengah titik akhir khusus domain mengembalikan status dan sebab yang jelas. Contohnya, kegagalan kawalan akses termasuk medan seperti reason, door_id, facility_id dan event_id.

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

Kod status

400 Bad Request

Permintaan itu cacat atau tiada medan yang diperlukan. Betulkan permintaan sebelum mencuba semula.

401 Unauthorized

Pengesahan gagal. Semak bahawa anda menggunakan HTTP Basic Auth dengan kunci rahsia API anda sebagai nama pengguna dan kata laluan kosong.

403 Forbidden

Kunci adalah sah tetapi operasi tidak dibenarkan. Punca biasa termasuk menggunakan kunci read-only untuk operasi tulis atau cuba mengakses kemudahan yang tidak mendayakan integrasi anda.

404 Not Found

Sumber yang diminta tidak ditemui atau tidak tersedia untuk integrasi anda.

409 Conflict

Permintaan bercanggah dengan keadaan semasa sumber. Untuk kawalan akses, ini boleh termasuk Door/Gate Controller yang berada dalam mod penyelenggaraan.

422 Unprocessable Entity

Permintaan ialah JSON yang sah tetapi gagal pengesahan semantik. Betulkan data sebelum mencuba semula.

429 Too Many Requests

Integrasi telah melebihi had kadar yang didokumenkan. Cuba semula dengan penundaan eksponen.

500 Internal Server Error

Performance Hub tidak dapat melengkapkan permintaan disebabkan ralat dalaman. Cuba semula dengan penundaan. Jika masalah berterusan, hubungi sokongan dengan titik akhir, cap masa dan badan respons.

503 Service Unavailable

Perkhidmatan atau peranti yang bergantung tidak tersedia. Untuk buka kunci Door/Gate Controller, ini boleh bermaksud pengawal berada di luar talian.

504 Gateway Timeout

Operasi telah tamat masa. Untuk buka kunci Door/Gate Controller, ini bermaksud buka kunci tidak disahkan sebelum tetingkap tamat masa.

Kegagalan Access Time Window

Pengesahan tetingkap gagal sebelum petikan yang tidak sah ditulis. Punca biasa yang tidak boleh dicuba semula termasuk:

  • access_time_windows_revision tiada apabila access_time_windows hadir.
  • Nilai epoch dalam bentuk rentetan, titik terapung atau berkemungkinan milisaat.
  • Zon waktu IANA yang tidak sah, selang terbalik, external_id pendua, blok mingguan bertindih atau blok semalaman yang tidak dipecahkan.
  • Nilai di luar had bilangan, panjang atau rentang yang didokumenkan.

Semakan berulang dengan kandungan dinormalkan yang berbeza ialah 409 Conflict. Selaraskan dengan keadaan berautoriti terkini dan peruntukkan semakan yang lebih baharu; jangan terus mencuba semula pasangan yang bercanggah. Semakan yang lebih lama dilaporkan sebagai petikan lapuk yang dilangkau dan tidak dibenarkan menulis ganti keadaan yang lebih baharu. scope_key yang tidak diketahui atau tidak dipetakan menyebabkan akses tidak diberikan dan patut dianggap sebagai amaran konfigurasi.

Jika penghantaran tamat masa atau menerima 5xx sementara, cuba semula petikan dinormalkan yang sama tepat dengan semakan yang sama. Jika pengambilan sumber huluan gagal, tinggalkan medan tetingkap sepenuhnya; jangan sekali-kali gantikannya dengan tatasusunan kosong.

Panduan cubaan semula

Cuba semula yang berikut dengan penundaan eksponen yang terhad:

  • 429
  • 500
  • 502
  • 503
  • 504

Jangan cuba semula yang berikut secara membuta tuli:

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

Untuk kawalan akses, sentiasa anggap respons tamat masa dan luar talian sebagai buka kunci yang gagal melainkan peraturan akses dan proses keselamatan anda sendiri menyatakan sebaliknya.

Butiran sokongan yang perlu disertakan

Semasa menghubungi sokongan, sertakan:

  • Titik akhir dan kaedah HTTP.
  • Cap masa dan zon waktu.
  • ID kunci rakan kongsi, bukan kunci rahsia.
  • Pengecam kemudahan yang digunakan.
  • ID rekod sumber daripada sistem anda.
  • Status dan badan respons.
  • event_id atau command_id jika ada.