Gestion des erreurs

L'API utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l'échec des requêtes. Cette page documente les formats d'erreur et les stratégies de gestion.

Formats des réponses d'erreur

Le format dépend de l'endroit où l'erreur est générée.

Erreurs d'authentification et de limite de débit (401 et 429)

Un petit objet JSON avec error, message et status. Les points de terminaison de modification de stratégie, le point de terminaison de code QR d'approvisionnement, et les points de terminaison de commande d'appareils autres que lock, lost-mode, found et message constituent l'exception : leur 429 utilise le format problem details ci-dessous, avec code et retryable.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded for device commands on this API key. Try again later.",
  "status": 429
}

Toutes les autres erreurs (par exemple 400, 403, 409, 422, 500, 502 et 503)

Problem details RFC 9457 avec le type de contenu application/problem+json. Les erreurs de validation ajoutent un tableau errors. Les points de terminaison de modification de stratégie, le point de terminaison de code QR d'approvisionnement, et les points de terminaison de commande d'appareils autres que lock, lost-mode, found et message ajoutent un membre code à chaque erreur sauf 401. Sur le point de terminaison de code QR d'approvisionnement, un corps qui n'est pas un JSON valide ou qui comporte un champ inconnu constitue également une exception : son erreur 400 n'a pas de code. Le membre retryable est décrit ci-dessous.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "status": 400,
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "errors": [
    { "field": "title", "index": null, "message": "must not be blank" }
  ]
}
ChampDescription
typeType d'erreur, ou about:blank
titleBref résumé, comme la formule de statut HTTP
statusLe code de statut HTTP
detailExplication lisible par l'humain de cette erreur
instanceLe chemin de la requête
errorsErreurs de validation au niveau du champ, chacune avec field, index et message (400 uniquement)
codeUn code d'erreur stable sur lequel brancher votre logique, comme not_found, forbidden ou internal_error. Envoyé par les points de terminaison de modification de stratégie, le point de terminaison du code QR de provisionnement et les points de terminaison de commande d'appareil autres que lock, lost-mode, found et message.
retryabletrue si la même requête peut être retentée. Renvoyé sur les erreurs 502 et 503 depuis chaque point de terminaison de commande d'appareil, sur 429 et 500 depuis les points de terminaison de commande autres que lock, lost-mode, found et message, et sur chaque erreur comportant un code depuis les points de terminaison de modification de stratégie et le point de terminaison de code QR d'approvisionnement.

Une erreur 404 pour un actif ou une stratégie inconnus possède un corps vide. Les points de terminaison de modification de stratégie, le point de terminaison de code QR d'approvisionnement, et les points de terminaison de commande d'appareils autres que lock, lost-mode, found et message constituent l'exception : leur 404 est au format problem details avec le code not_found.

Les points de terminaison de session Device User répondent 400, 404 et 409 avec application/problem+json et un membre code pour le branchement conditionnel ; ils n'envoient aucun membre retryable. Deux exceptions n'ont pas de code : 401 et 403, ainsi qu'une réponse 400 en cas de paramètre de requête non valide pour GET /device-user-logins. API Sessions d'utilisateurs d'appareils

Codes de statut HTTP

CodeDescription
400Paramètres de requête invalides ou corps de requête malformé
401Clé d'API manquante ou invalide
403La clé d'API n'a pas les autorisations requises pour ce point de terminaison
404La ressource demandée n'existe pas
429Limite de débit dépassée - réessayez après le temps spécifié
500Erreur interne du serveur - veuillez contacter le support si le problème persiste
503Service temporairement indisponible - veuillez réessayer plus tard

Réponses aux commandes d'appareil

Les points de terminaison de commande utilisent des codes d'état avec des règles spéciales de nouvelle tentative. Réessayer le mauvais code peut transmettre une commande deux fois à un appareil.

202Résultat inconnu. Ne pas renvoyer. Vérifiez d'abord l'historique des commandes.
500Erreur inattendue, avec le code internal_error en dehors des points de terminaison lock, lost-mode, found et message. On ignore si la commande a atteint l'appareil. Vérifiez l'appareil avant de réessayer.
503Non envoyé. Nouvelle tentative sans danger.
502Le fournisseur a rejeté la commande. Réessayez uniquement si retryable est true.
409L'appareil ne peut pas accepter cette commande. Toute nouvelle tentative échouera tant que son état n'aura pas changé.
422Le fournisseur a refusé la commande. Ne réessayez pas avec les mêmes arguments.
HTTP/1.1 202 Accepted

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "UNCONFIRMED",
  "detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
}
HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Command was not sent; it is safe to retry.",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "retryable": true
}

Référence complète des commandes d'appareil

Stratégie de nouvelle tentative

Ne réessayez que lorsque cela est sans danger. Les requêtes de lecture qui échouent avec une erreur temporaire peuvent être réessayées avec un intervalle exponentiel. Une commande d'appareil doit respecter les règles de la section relative aux réponses des commandes d'appareils. Après une erreur de modification de stratégie ou de code QR d'approvisionnement, suivez la valeur de son champ retryable, et après une erreur inattendue lors de l'application, lisez la proposition avant d'en soumettre une nouvelle.

  • Pour les erreurs 429, attendez le nombre de secondes indiqué dans l'en-tête Retry-After avant de réessayer.
  • Pour les erreurs 5xx sur les requêtes de lecture, utilisez un intervalle exponentiel (1s, 2s, 4s, 8s...) avec gigue (jitter). Pour les commandes d'appareils, ne réessayez qu'un code 503 (non envoyé) ou un code 502 dont le champ retryable est défini sur true. Après un code 202 ou 500, vérifiez l'appareil avant de renvoyer la commande.
  • Définissez un nombre maximum de nouvelles tentatives (par exemple, 3 à 5 tentatives) pour éviter les boucles infinies

Limitation du taux

Lorsque vous dépassez la limite de requêtes MCP, ou que vous appelez le point de terminaison lock, lost-mode, found ou message au-delà de la limite de commandes, l'API renvoie HTTP 429 Too Many Requests avec un en-tête Retry-After et un corps JSON contenant error, message et status. Les autres points de terminaison de commande d'appareil, les points de terminaison de modification de stratégie et le point de terminaison de code QR d'approvisionnement envoient également Retry-After au-delà de la même limite, mais leur corps est au format problem details avec le code rate_limited et retryable défini à true. Lorsqu'une commande MCP, une modification de stratégie ou un appel d'outil d'approvisionnement dépasse la limite de commandes, le résultat est une erreur d'outil dont le texte indique combien de secondes attendre.

Utilisez l'en-tête Retry-After, ou les secondes indiquées dans une erreur d'outil, pour décider du moment où réessayer. L'API n'envoie pas d'en-têtes X-RateLimit-Limit, X-RateLimit-Remaining ou X-RateLimit-Reset.

Erreurs de validation

Pour les erreurs 400 causées par un corps de requête non valide, le format problem details inclut un tableau errors avec une entrée par champ non valide. D'autres erreurs 400, comme une valeur lastSeenBefore non valide, expliquent le problème dans detail.

Bonnes pratiques de gestion des erreurs

  • Vérifiez toujours le code d'état HTTP avant d'analyser le corps de la réponse
  • Respectez Retry-After sur les erreurs 429 et utilisez un intervalle exponentiel pour les erreurs 5xx sur les requêtes de lecture. Pour les commandes d'appareils, ne réessayez qu'un code 503 ou un code 502 dont le champ retryable est défini sur true, et ne renvoyez jamais après un code 202 ou 500 sans avoir d'abord vérifié l'appareil.
  • Consignez le statut HTTP ainsi que le champ detail ou message provenant du corps de l'erreur à des fins de débogage. Les corps d'erreur n'incluent pas les champs timestamp ou path.
  • Traiter les codes d'erreur spécifiques différemment (par exemple, 401 déclenche une réauthentification)

Choisissez votre horaire

Chargement...
Ouvrir le calendrier de réservation