Erreurs
La Partner API utilise des codes de statut HTTP standard et des corps de réponse JSON pour expliquer pourquoi une requête a échoué.
Structure des réponses d'erreur
La plupart des erreurs de l'API renvoient un corps JSON contenant un message et, le cas échéant, des détails structurés.
{
"success": false,
"message": "Request body.members[0].member_id is required"
}
Certains endpoints propres à un domaine renvoient un statut et un motif explicites. Par exemple, les échecs de contrôle d'accès incluent des champs tels que reason, door_id, facility_id et event_id.
{
"status": "failed",
"reason": "device_offline",
"door_id": "00000000000000000000000000000007",
"facility_id": "550e8400-e29b-41d4-a716-446655440000",
"event_id": "00000000-0000-0000-0000-000000000045"
}
Codes de statut
400 Bad Request
La requête est mal formée ou des champs obligatoires sont manquants. Corrigez la requête avant de réessayer.
401 Unauthorized
L'authentification a échoué. Vérifiez que vous utilisez l'authentification HTTP Basic avec votre clé secrète API comme nom d'utilisateur et un mot de passe vide.
403 Forbidden
La clé est valide, mais l'opération n'est pas autorisée. Les causes courantes sont l'utilisation d'une clé en lecture seule pour une opération d'écriture ou une tentative d'accès à une installation pour laquelle votre intégration n'est pas activée.
404 Not Found
La ressource demandée est introuvable ou n'est pas disponible pour votre intégration.
409 Conflict
La requête est en conflit avec l'état actuel de la ressource. Pour le contrôle d'accès, cela peut signifier qu'un contrôleur de porte/portail est en mode de maintenance.
422 Unprocessable Entity
La requête est un JSON valide, mais elle échoue à la validation sémantique. Corrigez les données avant de réessayer.
429 Too Many Requests
L'intégration a dépassé la limite de débit documentée. Réessayez avec un backoff exponentiel.
500 Internal Server Error
Performance Hub n'a pas pu traiter la requête en raison d'une erreur interne. Réessayez avec un backoff. Si le problème persiste, contactez l'assistance en indiquant l'endpoint, l'horodatage et le corps de la réponse.
503 Service Unavailable
Un service ou un appareil dont dépend la requête est indisponible. Pour les déverrouillages de contrôleurs de porte/portail, cela peut signifier que le contrôleur est hors ligne.
504 Gateway Timeout
Le délai de l'opération a expiré. Pour les déverrouillages de contrôleurs de porte/portail, cela signifie que le déverrouillage n'a pas été confirmé avant l'expiration du délai.
Échecs liés aux Access Time Windows
La validation des plages échoue avant l'écriture de l'instantané invalide. Les causes courantes qui ne justifient pas une nouvelle tentative sont notamment :
- L'absence de
access_time_windows_revisionlorsqueaccess_time_windowsest présent. - Des valeurs d'epoch sous forme de chaîne, de nombre à virgule flottante ou probablement exprimées en millisecondes.
- Un fuseau horaire IANA invalide, un intervalle inversé, un
external_iden double, des blocs hebdomadaires qui se chevauchent ou un bloc de nuit qui n'a pas été scindé. - Une valeur qui dépasse les limites documentées de nombre, de longueur ou d'étendue.
Une révision répétée avec un contenu normalisé différent renvoie une erreur 409 Conflict. Effectuez un rapprochement avec le dernier état de référence et attribuez une révision plus récente ; ne continuez pas à réessayer la paire en conflit. Une révision plus ancienne est signalée comme un instantané obsolète ignoré au lieu d'être autorisée à écraser un état plus récent. Un scope_key inconnu ou sans correspondance entraîne un refus d'autorisation par défaut et doit être traité comme une alerte de configuration.
Si la livraison expire ou reçoit une erreur 5xx temporaire, renvoyez exactement le même instantané normalisé avec la même révision. Si la récupération depuis la source en amont a échoué, omettez entièrement le champ des plages ; ne le remplacez jamais par un tableau vide.
Recommandations pour les nouvelles tentatives
Réessayez les codes suivants avec un backoff exponentiel limité :
429500502503504
Ne réessayez pas aveuglément les codes suivants :
400401403404409422
Pour le contrôle d'accès, considérez toujours les réponses d'expiration de délai et d'appareil hors ligne comme des déverrouillages en échec, sauf si vos propres règles d'accès et processus de sécurité en disposent autrement.
Informations à fournir à l'assistance
Lorsque vous contactez l'assistance, indiquez :
- L'endpoint et la méthode HTTP.
- L'horodatage et le fuseau horaire.
- L'ID de la clé partenaire, et non la clé secrète.
- L'identifiant d'installation utilisé.
- L'ID de l'enregistrement source dans votre système.
- Le statut et le corps de la réponse.
- L'
event_idou lecommand_id, le cas échéant.