Διαχείριση σφαλμάτων
Το API χρησιμοποιεί συμβατικούς κωδικούς απόκρισης HTTP για να υποδείξει την επιτυχία ή την αποτυχία αιτημάτων. Αυτή η σελίδα τεκμηριώνει τις μορφές σφαλμάτων και τις στρατηγικές χειρισμού.
Μορφή Απάντησης Σφάλματος
Όλες οι απαντήσεις σφάλματος ακολουθούν μια συνεπή δομή JSON:
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Πεδίο | Περιγραφή |
|---|---|
| error | Κωδικός σφάλματος αναγνώσιμος από μηχανή |
| message | Περιγραφή σφάλματος αναγνώσιμη από άνθρωπο |
| timestamp | Πότε συνέβη το σφάλμα |
| path | Η διαδρομή του αιτούμενου τελικού σημείου |
| details | Πρόσθετες λεπτομέρειες για σφάλματα επικύρωσης (προαιρετικό) |
Κωδικοί Κατάστασης HTTP
| Κωδικός | Περιγραφή |
|---|---|
| 400 | Μη έγκυρες παράμετροι αιτήματος ή ακατάλληλο σώμα αιτήματος |
| 401 | Λείπει ή μη έγκυρο κλειδί API |
| 403 | Το κλειδί API δεν έχει τα απαιτούμενα δικαιώματα για αυτό το τελικό σημείο |
| 404 | Ο ζητούμενος πόρος δεν υπάρχει |
| 429 | Έχει ξεπεραστεί το όριο ρυθμού - δοκιμάστε ξανά μετά την καθορισμένη ώρα |
| 500 | Εσωτερικό σφάλμα διακομιστή - επικοινωνήστε με την υποστήριξη εάν επιμένει |
| 503 | Η υπηρεσία είναι προσωρινά μη διαθέσιμη - δοκιμάστε ξανά αργότερα |
Στρατηγική Επαναδοκιμής
Για προσωρινά σφάλματα, υλοποιήστε μια στρατηγική επαναδοκιμής με εκθετική καθυστέρηση:
- Για σφάλματα 429, περιμένετε τον χρόνο που καθορίζεται στην κεφαλίδα X-RateLimit-Reset πριν δοκιμάσετε ξανά.
- Για σφάλματα 5xx, χρησιμοποιήστε εκθετική καθυστέρηση (1 δευτ., 2 δευτ., 4 δευτ., 8 δευτ. ...) με τυχαιότητα.
- Ορίστε έναν μέγιστο αριθμό επαναδοκιμών (π.χ., 3-5 προσπάθειες) για να αποφύγετε ατέρμονους βρόχους.
Περιορισμός Ρυθμού
Όταν υπερβαίνετε το όριο ρυθμού, το API επιστρέφει έναν κωδικό κατάστασης 429 με λεπτομέρειες σχετικά με το πότε μπορείτε να δοκιμάσετε ξανά:
Χρησιμοποιήστε το πεδίο retryAfter ή την κεφαλίδα X-RateLimit-Reset για να προσδιορίσετε πότε να επαναλάβετε το αίτημά σας.
Σφάλματα Επικύρωσης
Για σφάλματα 400, η απόκριση περιλαμβάνει έναν πίνακα details με συγκεκριμένα σφάλματα σε επίπεδο πεδίου:
Βέλτιστες Πρακτικές Διαχείρισης Σφαλμάτων
- Ελέγχετε πάντα τον κωδικό κατάστασης HTTP πριν αναλύσετε το σώμα της απόκρισης
- Υλοποιήστε εκθετική διακοπή για σφάλματα 429 και 5xx
- Καταγράψτε τα σφάλματα με τη χρονική σήμανση και τη διαδρομή για αποσφαλμάτωση
- Διαχείριση συγκεκριμένων κωδικών σφαλμάτων διαφορετικά (π.χ., 401 ενεργοποιεί επανα-πιστοποίηση)