Kesalahan

Partner API menggunakan kode status HTTP standar dan isi respons JSON untuk menjelaskan mengapa suatu permintaan gagal.

Bentuk respons kesalahan

Sebagian besar kesalahan API mengembalikan isi JSON dengan pesan dan, jika tersedia, detail terstruktur.

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

Beberapa endpoint khusus domain mengembalikan status dan alasan secara eksplisit. Misalnya, kegagalan kontrol akses menyertakan bidang 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"
}

Kode status

400 Bad Request

Permintaan salah format atau tidak memiliki bidang yang wajib. Perbaiki permintaan sebelum mencoba ulang.

401 Unauthorized

Autentikasi gagal. Pastikan Anda menggunakan HTTP Basic Auth dengan kunci rahasia API sebagai nama pengguna dan kata sandi kosong.

403 Forbidden

Kunci valid, tetapi operasi tidak diizinkan. Penyebab umum meliputi penggunaan kunci read-only untuk operasi tulis atau upaya mengakses fasilitas yang tidak mengaktifkan integrasi Anda.

404 Not Found

Sumber daya yang diminta tidak ditemukan atau tidak tersedia untuk integrasi Anda.

409 Conflict

Permintaan bertentangan dengan status sumber daya saat ini. Untuk kontrol akses, hal ini dapat mencakup Door/Gate Controller yang sedang dalam mode pemeliharaan.

422 Unprocessable Entity

Permintaan berupa JSON yang valid tetapi gagal dalam validasi semantik. Perbaiki data sebelum mencoba ulang.

429 Too Many Requests

Integrasi melampaui batas laju yang didokumentasikan. Coba ulang dengan exponential backoff.

500 Internal Server Error

Performance Hub tidak dapat menyelesaikan permintaan karena kesalahan internal. Coba ulang dengan backoff. Jika masalah berlanjut, hubungi dukungan dengan menyertakan endpoint, stempel waktu, dan isi respons.

503 Service Unavailable

Layanan atau perangkat yang dibutuhkan tidak tersedia. Untuk pembukaan kunci Door/Gate Controller, ini dapat berarti pengontrol sedang offline.

504 Gateway Timeout

Operasi melewati batas waktu. Untuk pembukaan kunci Door/Gate Controller, ini berarti pembukaan kunci tidak dikonfirmasi sebelum jangka waktu batas waktu berakhir.

Kegagalan Access Time Window

Validasi jendela gagal sebelum snapshot yang tidak valid ditulis. Penyebab umum yang tidak dapat dicoba ulang meliputi:

• access_time_windows_revision tidak ada padahal access_time_windows ada.
• Nilai epoch berupa string, bilangan floating-point, atau kemungkinan dalam milidetik.
• Zona waktu IANA yang tidak valid, interval terbalik, external_id duplikat, blok mingguan yang tumpang tindih, atau blok semalam yang tidak dipisah.
• Nilai di luar batas jumlah, panjang, atau rentang yang didokumentasikan.

Revisi berulang dengan konten ternormalisasi yang berbeda menghasilkan 409 Conflict. Lakukan rekonsiliasi dengan status otoritatif terbaru dan alokasikan revisi yang lebih baru; jangan terus mencoba ulang pasangan yang bertentangan. Revisi yang lebih lama dilaporkan sebagai snapshot usang yang dilewati, bukan dibiarkan menimpa status yang lebih baru. Untuk scope_key yang tidak dikenal atau tidak dipetakan, otorisasi ditolak sehingga tidak ada akses yang diberikan, dan hal ini harus diperlakukan sebagai peringatan konfigurasi.

Jika pengiriman melewati batas waktu atau menerima 5xx sementara, coba ulang snapshot ternormalisasi yang sama persis dengan revisi yang sama. Jika pengambilan dari sumber upstream gagal, hilangkan bidang jendela sepenuhnya; jangan pernah menggantinya dengan array kosong.

Panduan percobaan ulang

Coba ulang respons berikut dengan exponential backoff yang terbatas:

• 429
• 500
• 502
• 503
• 504

Jangan mencoba ulang respons berikut secara membabi buta:

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

Untuk kontrol akses, selalu perlakukan respons batas waktu dan offline sebagai buka kunci yang gagal, kecuali aturan akses dan proses keselamatan Anda sendiri menentukan lain.

Detail yang perlu disertakan untuk dukungan

Saat menghubungi dukungan, sertakan:

• Endpoint dan metode HTTP.
• Stempel waktu dan zona waktu.
• ID kunci mitra, bukan kunci rahasianya.
• Pengidentifikasi fasilitas yang digunakan.
• ID rekaman sumber dari sistem Anda.
• Status dan isi respons.
• event_id atau command_id jika tersedia.