Διαχείριση σφαλμάτων

Το API χρησιμοποιεί συμβατικούς κωδικούς απόκρισης HTTP για να υποδείξει την επιτυχία ή την αποτυχία αιτημάτων. Αυτή η σελίδα τεκμηριώνει τις μορφές σφαλμάτων και τις στρατηγικές χειρισμού.

Μορφές απόκρισης σφάλματος

Η μορφή εξαρτάται από το πού παράγεται το σφάλμα.

Σφάλματα ελέγχου ταυτότητας και ορίου ρυθμού (401 και 429)

Ένα μικρό αντικείμενο JSON με error, message και status. Τα τελικά σημεία αλλαγής πολιτικής, το τελικό σημείο κωδικού QR προετοιμασίας και τα τελικά σημεία εντολών συσκευής εκτός από lock, lost-mode, found και message αποτελούν εξαίρεση: το 429 τους χρησιμοποιεί τη μορφή λεπτομερειών προβλήματος παρακάτω, με code και 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
}

Όλα τα υπόλοιπα σφάλματα (για παράδειγμα 400, 403, 409, 422, 500, 502 και 503)

RFC 9457 λεπτομέρειες προβλήματος με τύπο περιεχομένου application/problem+json. Τα σφάλματα επικύρωσης προσθέτουν έναν πίνακα errors. Τα τελικά σημεία αλλαγής πολιτικής, το τελικό σημείο κωδικού QR προετοιμασίας και τα τελικά σημεία εντολών συσκευής εκτός από lock, lost-mode, found και message προσθέτουν ένα πεδίο code σε κάθε σφάλμα εκτός από το 401. Στο τελικό σημείο κωδικού QR προετοιμασίας, ένα σώμα που δεν είναι έγκυρο JSON ή περιέχει άγνωστο πεδίο αποτελεί επίσης εξαίρεση: το 400 του δεν έχει code. Το πεδίο retryable περιγράφεται παρακάτω.

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" }
  ]
}
ΠεδίοΠεριγραφή
typeΤύπος σφάλματος, ή about:blank
titleΣύντομη σύνοψη, όπως η φράση κατάστασης HTTP
statusΟ κωδικός κατάστασης HTTP
detailΕυανάγνωστη από τον άνθρωπο εξήγηση αυτού του σφάλματος
instanceΗ διαδρομή του αιτήματος
errorsΣφάλματα επικύρωσης σε επίπεδο πεδίου, το καθένα με field, index και message (μόνο για 400)
codeΈνας σταθερός κωδικός σφάλματος για διακλάδωση, όπως not_found, forbidden ή internal_error. Αποστέλλεται από τα τελικά σημεία αλλαγής πολιτικής, το τελικό σημείο κωδικού QR προετοιμασίας και τα τελικά σημεία εντολών συσκευής εκτός των lock, lost-mode, found και message.
retryabletrue εάν το ίδιο αίτημα μπορεί να επαναληφθεί. Αποστέλλεται στα 502 και 503 από κάθε τελικό σημείο εντολών συσκευής, στα 429 και 500 από τα τελικά σημεία εντολών εκτός των lock, lost-mode, found και message, και σε κάθε σφάλμα που φέρει code από τα τελικά σημεία αλλαγής πολιτικής και το τελικό σημείο κωδικού QR προετοιμασίας.

Ένα 404 για ένα άγνωστο στοιχείο ή πολιτική έχει κενό σώμα. Τα τελικά σημεία αλλαγής πολιτικής, το τελικό σημείο κωδικού QR προετοιμασίας και τα τελικά σημεία εντολών συσκευής εκτός από lock, lost-mode, found και message αποτελούν εξαίρεση: το 404 τους είναι λεπτομέρειες προβλήματος με code not_found.

Τα τελικά σημεία συνεδρίας Device User απαντούν με 400, 404 και 409 με application/problem+json και ένα μέλος code για διακλάδωση· δεν στέλνουν μέλος retryable. Δύο εξαιρέσεις δεν έχουν code: το 401 και το 403, καθώς και ένα 400 για μη έγκυρη παράμετρο ερωτήματος του GET /device-user-logins. API συνεδριών Device User

Κωδικοί Κατάστασης HTTP

ΚωδικόςΠεριγραφή
400Μη έγκυρες παράμετροι αιτήματος ή ακατάλληλο σώμα αιτήματος
401Λείπει ή μη έγκυρο κλειδί API
403Το κλειδί API δεν έχει τα απαιτούμενα δικαιώματα για αυτό το τελικό σημείο
404Ο ζητούμενος πόρος δεν υπάρχει
429Έχει ξεπεραστεί το όριο ρυθμού - δοκιμάστε ξανά μετά την καθορισμένη ώρα
500Εσωτερικό σφάλμα διακομιστή - επικοινωνήστε με την υποστήριξη εάν επιμένει
503Η υπηρεσία είναι προσωρινά μη διαθέσιμη - δοκιμάστε ξανά αργότερα

Αποκρίσεις εντολών συσκευής

Τα τελικά σημεία εντολών χρησιμοποιούν κωδικούς κατάστασης με ειδικούς κανόνες επανάληψης. Η επανάληψη για λάθος κωδικό μπορεί να παραδώσει μια εντολή σε μια συσκευή δύο φορές.

202Άγνωστο αποτέλεσμα. Μην επαναλάβετε την αποστολή. Ελέγξτε πρώτα το ιστορικό εντολών.
500Μη αναμενόμενο σφάλμα, με κωδικό internal_error εκτός των τελικών σημείων lock, lost-mode, found και message. Το εάν η εντολή έφτασε στη συσκευή είναι άγνωστο. Ελέγξτε τη συσκευή πριν προσπαθήσετε ξανά.
503Δεν στάλθηκε. Ασφαλές για επανάληψη.
502Ο πάροχος απέρριψε την εντολή. Επαναλάβετε μόνο εάν το retryable είναι true.
409Η συσκευή δεν μπορεί να δεχτεί αυτήν την εντολή. Η επανάληψη θα αποτυγχάνει μέχρι να αλλάξει η κατάστασή της.
422Ο πάροχος αρνήθηκε την εντολή. Μην επαναλάβετε με τα ίδια ορίσματα.
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
}

Πλήρης οδηγός αναφοράς εντολών συσκευής

Στρατηγική Επαναδοκιμής

Επαναλάβετε τη δοκιμή μόνο όταν είναι ασφαλές. Τα αιτήματα ανάγνωσης που αποτυγχάνουν με παροδικό σφάλμα μπορούν να επαναληφθούν με εκθετική οπισθοχώρηση. Μια εντολή συσκευής πρέπει να ακολουθεί τους κανόνες στην ενότητα αποκρίσεων εντολών συσκευής. Μετά από σφάλμα αλλαγής πολιτικής ή κωδικού QR παροχής, ακολουθήστε το πεδίο retryable και μετά από ένα μη αναμενόμενο σφάλμα στο apply, διαβάστε την πρόταση πριν προτείνετε ξανά.

  • Για σφάλματα 429, περιμένετε τον αριθμό δευτερολέπτων στην κεφαλίδα Retry-After πριν δοκιμάσετε ξανά.
  • Για σφάλματα 5xx σε αιτήματα ανάγνωσης, χρησιμοποιήστε εκθετική οπισθοχώρηση (1s, 2s, 4s, 8s...) με jitter. Για εντολές συσκευών, δοκιμάστε ξανά μόνο ένα 503 (δεν στάλθηκε) ή ένα 502 με το retryable ορισμένο σε true. Μετά από ένα 202 ή ένα 500, ελέγξτε τη συσκευή πριν στείλετε ξανά.
  • Ορίστε έναν μέγιστο αριθμό επαναδοκιμών (π.χ., 3-5 προσπάθειες) για να αποφύγετε ατέρμονους βρόχους.

Περιορισμός Ρυθμού

Όταν υπερβαίνετε το όριο αιτημάτων MCP ή καλείτε το τελικό σημείο lock, lost-mode, found ή message πέρα από το όριο εντολών, το API επιστρέφει HTTP 429 Too Many Requests με μια κεφαλίδα Retry-After και ένα σώμα JSON με error, message και status. Τα υπόλοιπα τελικά σημεία εντολών συσκευής, τα τελικά σημεία αλλαγής πολιτικής και το τελικό σημείο κωδικού QR προετοιμασίας στέλνουν επίσης Retry-After κατά την υπέρβαση του ίδιου ορίου, αλλά το σώμα τους αποτελεί λεπτομέρειες προβλήματος με code rate_limited και retryable true. Όταν μια εντολή MCP, μια αλλαγή πολιτικής ή μια κλήση εργαλείου προετοιμασίας υπερβαίνει το όριο εντολών, το αποτέλεσμα είναι ένα σφάλμα εργαλείου του οποίου το κείμενο αναφέρει πόσα δευτερόλεπτα πρέπει να περιμένετε.

Χρησιμοποιήστε την κεφαλίδα Retry-After ή τα δευτερόλεπτα που δίνονται σε ένα σφάλμα εργαλείου για να αποφασίσετε πότε θα επαναλάβετε τη δοκιμή. Το API δεν αποστέλλει κεφαλίδες X-RateLimit-Limit, X-RateLimit-Remaining ή X-RateLimit-Reset.

Σφάλματα Επικύρωσης

Για σφάλματα 400 που προκαλούνται από μη έγκυρο σώμα αιτήματος, οι λεπτομέρειες προβλήματος περιλαμβάνουν έναν πίνακα errors με μία καταχώριση ανά μη έγκυρο πεδίο. Άλλα σφάλματα 400, όπως μια μη έγκυρη τιμή lastSeenBefore, εξηγούν το πρόβλημα λεπτομερώς.

Βέλτιστες Πρακτικές Διαχείρισης Σφαλμάτων

  • Ελέγχετε πάντα τον κωδικό κατάστασης HTTP πριν αναλύσετε το σώμα της απόκρισης
  • Ακολουθήστε το Retry-After στο 429 και χρησιμοποιήστε εκθετική οπισθοχώρηση για σφάλματα 5xx σε αιτήματα ανάγνωσης. Για εντολές συσκευών, δοκιμάστε ξανά μόνο ένα 503 ή ένα 502 με το retryable ορισμένο σε true και μην στέλνετε ποτέ ξανά μετά από ένα 202 ή ένα 500 χωρίς να ελέγξετε πρώτα τη συσκευή.
  • Καταγράψτε την κατάσταση HTTP και το detail ή message από το σώμα του σφάλματος για εντοπισμό σφαλμάτων. Τα σώματα σφαλμάτων δεν περιλαμβάνουν πεδία timestamp ή path.
  • Διαχείριση συγκεκριμένων κωδικών σφαλμάτων διαφορετικά (π.χ., 401 ενεργοποιεί επανα-πιστοποίηση)

Επιλέξτε την ώρα σας

Φόρτωση...
Άνοιγμα ημερολογίου κρατήσεων