שגיאות

ה-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

האינטגרציה חרגה ממגבלת הקצב המתועדת. נסו שוב עם השהיה מעריכית (exponential backoff).

500 Internal Server Error

Performance Hub לא הצליח להשלים את הבקשה בגלל שגיאה פנימית. נסו שוב עם השהיה. אם הבעיה נמשכת, פנו לתמיכה וציינו את נקודת הקצה, חותמת הזמן וגוף התגובה.

503 Service Unavailable

שירות או מכשיר שהבקשה תלויה בהם אינם זמינים. בפתיחות של Door/Gate Controller, המשמעות יכולה להיות שהבקר אינו מקוון.

504 Gateway Timeout

הזמן הקצוב לפעולה פג. בפתיחות של Door/Gate Controller, המשמעות היא שהפתיחה לא אושרה לפני תום חלון הזמן הקצוב.

כשלים ב-Access Time Windows

אימות החלונות נכשל לפני שתמונת המצב הלא תקינה נכתבת. סיבות נפוצות שאין טעם לנסות בהן שוב כוללות:

• היעדר 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.
• חותמת זמן ואזור זמן.
• מזהה מפתח השותף, לא המפתח הסודי.
• מזהה המתקן שבו נעשה שימוש.
• מזהה רשומת המקור מהמערכת שלכם.
• סטטוס התגובה וגוף התגובה.
• event_id או command_id, כשהם זמינים.