Fehlerbehandlung

Die API verwendet konventionelle HTTP-Antwortcodes, um den Erfolg oder Misserfolg von Anfragen anzuzeigen. Diese Seite dokumentiert Fehlerformate und Behandlungsstrategien.

Formate von Fehlerantworten

Das Format hängt davon ab, wo der Fehler erzeugt wird.

Authentifizierungs- und Ratenbegrenzungsfehler (401 und 429)

Ein kleines JSON-Objekt mit error, message und status. Die Endpunkte für Richtlinienänderungen, der Endpunkt für Provisionierungs-QR-Codes und die Gerätebefehl-Endpunkte außer lock, lost-mode, found und message bilden die Ausnahme: Deren 429 verwendet das unten beschriebene Problem-Details-Format mit code und 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
}

Alle anderen Fehler (zum Beispiel 400, 403, 409, 422, 500, 502 und 503)

RFC 9457 Problem Details mit dem Inhaltstyp application/problem+json. Validierungsfehler fügen ein errors-Array hinzu. Die Endpunkte für Richtlinienänderungen, der Endpunkt für Provisionierungs-QR-Codes und die Gerätebefehl-Endpunkte außer lock, lost-mode, found und message fügen jedem Fehler außer 401 ein code-Element hinzu. Beim Endpunkt für Provisionierungs-QR-Codes ist ein Body, der kein gültiges JSON ist oder ein unbekanntes Feld enthält, ebenfalls eine Ausnahme: Dessen 400 hat keinen code. Das retryable-Element wird unten beschrieben.

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" }
  ]
}

Feld	Beschreibung
type	Fehlertyp oder about:blank
title	Kurze Zusammenfassung, wie beispielsweise die HTTP-Statusmeldung
status	Der HTTP-Statuscode
detail	Für Menschen lesbare Erklärung dieses Fehlers
instance	Der Anfragepfad
errors	Validierungsfehler auf Feldebene, jeweils mit field, index und message (nur 400)
code	Ein stabiler Fehlercode zur Verzweigung, wie z. B. not_found, forbidden oder internal_error. Wird von den Endpunkten für Richtlinienänderungen, dem Endpunkt für Bereitstellungs-QR-Codes und den Gerätebefehl-Endpunkten außer lock, lost-mode, found und message gesendet.
retryable	true, wenn dieselbe Anfrage wiederholt werden darf. Wird bei 502 und 503 von jedem Gerätebefehl-Endpunkt gesendet, bei 429 und 500 von den Befehl-Endpunkten außer lock, lost-mode, found und message, sowie bei jedem Fehler, der einen code von den Endpunkten für Richtlinienänderungen und dem Endpunkt für Provisionierungs-QR-Codes enthält.

Ein 404 für ein unbekanntes Asset oder eine unbekannte Richtlinie hat einen leeren Body. Die Endpunkte für Richtlinienänderungen, der Endpunkt für Provisionierungs-QR-Codes und die Gerätebefehl-Endpunkte außer lock, lost-mode, found und message bilden die Ausnahme: Deren 404 sind Problem Details mit dem code not_found.

HTTP-Statuscodes

Code	Beschreibung
400	Ungültige Anfrageparameter oder fehlerhafter Anfragekörper
401	Fehlender oder ungültiger API-Schlüssel
403	API-Schlüssel verfügt nicht über die erforderlichen Berechtigungen für diesen Endpunkt
404	Die angeforderte Ressource existiert nicht
429	Rate-Limit überschritten - bitte nach der angegebenen Zeit erneut versuchen
500	Interner Serverfehler - bitte kontaktieren Sie den Support, falls das Problem weiterhin besteht
503	Dienst vorübergehend nicht verfügbar - versuchen Sie es später erneut

Antworten auf Gerätebefehle

Die Befehls-Endpunkte verwenden Statuscodes mit speziellen Wiederholungsregeln. Ein erneuter Versuch beim falschen Code kann dazu führen, dass ein Befehl doppelt an ein Gerät zugestellt wird.

202	Ergebnis unbekannt. Nicht erneut senden. Überprüfen Sie zuerst den Befehlsverlauf.
500	Unerwarteter Fehler mit dem Code internal_error außerhalb der Endpunkte lock, lost-mode, found und message. Ob der Befehl das Gerät erreicht hat, ist unbekannt. Überprüfen Sie das Gerät, bevor Sie es erneut versuchen.
503	Nicht gesendet. Wiederholung sicher möglich.
502	Der Anbieter hat den Befehl abgelehnt. Versuchen Sie es nur erneut, wenn retryable true ist.
409	Das Gerät kann diesen Befehl nicht annehmen. Ein erneuter Versuch schlägt fehl, bis sich sein Status ändert.
422	Der Anbieter hat den Befehl verweigert. Versuchen Sie es nicht mit denselben Argumenten erneut.

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
}

Vollständige Referenz zu Gerätebefehlen

Wiederholungsstrategie

Versuchen Sie es nur erneut, wenn es sicher ist. Leseanfragen, die mit einem vorübergehenden Fehler fehlschlagen, können mit exponentiellem Backoff wiederholt werden. Ein Gerätebefehl muss den Regeln im Abschnitt zu den Antworten auf Gerätebefehle folgen. Befolgen Sie nach einem Richtlinienänderungs- oder Bereitstellungs-QR-Code-Fehler dessen retryable-Feld, und lesen Sie nach einem unerwarteten Fehler bei apply den Vorschlag, bevor Sie ihn erneut vorschlagen.

Warten Sie bei 429-Fehlern die Anzahl der Sekunden im Retry-After-Header ab, bevor Sie den Vorgang wiederholen.
Verwenden Sie bei 5xx-Fehlern bei Leseanfragen exponentielles Backoff (1s, 2s, 4s, 8s...) mit Jitter. Wiederholen Sie bei Gerätebefehlen nur einen 503 (nicht gesendet) oder einen 502 mit auf true gesetztem retryable. Überprüfen Sie nach einem 202 oder 500 das Gerät, bevor Sie es erneut senden.
Legen Sie eine maximale Anzahl von Wiederholungsversuchen fest (z. B. 3-5 Versuche), um Endlosschleifen zu vermeiden.

Ratenbegrenzung

Wenn Sie das MCP-Anfragelimit überschreiten oder den lock-, lost-mode-, found- oder message-Endpunkt über dem Befehlslimit aufrufen, gibt die API HTTP 429 Too Many Requests mit einem Retry-After-Header und einem JSON-Body mit error, message und status zurück. Die anderen Gerätebefehl-Endpunkte, die Endpunkte für Richtlinienänderungen und der Endpunkt für Provisionierungs-QR-Codes senden bei derselben Limitüberschreitung ebenfalls Retry-After, ihr Body besteht jedoch aus Problem Details mit dem code rate_limited und retryable true. Wenn ein MCP-Befehl, eine Richtlinienänderung oder ein Aufruf des Provisionierungs-Tools das Befehlslimit überschreitet, ist das Ergebnis ein Tool-Fehler, dessen Text angibt, wie viele Sekunden gewartet werden müssen.

Verwenden Sie den Retry-After-Header oder die in einem Tool-Fehler angegebenen Sekunden, um zu entscheiden, wann der Vorgang wiederholt werden soll. Die API sendet keine X-RateLimit-Limit-, X-RateLimit-Remaining- oder X-RateLimit-Reset-Header.

Validierungsfehler

Bei 400-Fehlern, die durch einen ungültigen Anfrage-Body verursacht werden, enthalten die Problem Details ein errors-Array mit einem Eintrag pro ungültigem Feld. Andere 400-Fehler, wie z. B. ein ungültiger lastSeenBefore-Wert, erläutern das Problem in detail.

Best Practices für die Fehlerbehandlung

Überprüfen Sie immer den HTTP-Statuscode, bevor Sie den Antwortkörper analysieren
Befolgen Sie Retry-After bei 429 und verwenden Sie exponentielles Backoff bei 5xx-Fehlern bei Leseanfragen. Wiederholen Sie bei Gerätebefehlen nur einen 503 oder einen 502 mit auf true gesetztem retryable und senden Sie nach einem 202 oder einem 500 niemals erneut, ohne zuvor das Gerät zu überprüfen.
Protokollieren Sie den HTTP-Status und das Feld detail oder message aus dem Fehlertext zur Fehlersuche. Fehlertexte enthalten keine timestamp- oder path-Felder.
Spezifische Fehlercodes unterschiedlich behandeln (z. B. 401 löst erneute Authentifizierung aus)