Διαχείριση σφαλμάτων
Το 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. |
| retryable | true εάν το ίδιο αίτημα μπορεί να επαναληφθεί. Αποστέλλεται στα 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 ενεργοποιεί επανα-πιστοποίηση)