Κάθε σφάλμα, εξηγημένο σε σταθερή διεύθυνση.
Αυτή η σελίδα είναι αναφορά λειτουργίας, όχι διαφημιστικό κείμενο. Κάθε κατηγορία σφάλματος του Connect API έχει εδώ μόνιμη άγκυρα· οι αποκρίσεις σφάλματος του API θα παραπέμπουν σε αυτές τις διευθύνσεις. Λαμβάνετε την πιθανή αιτία και τη διόρθωση — με αυτή τη σειρά. Επιστροφή στην τεκμηρίωση για προγραμματιστές.
Κλειδί που λείπει, κακοσχηματισμένο ή άγνωστο
Το API πιστοποιεί αποκλειστικά μέσω της κεφαλίδας Authorization: Bearer vgk_… — ποτέ μέσω cookie συνεδρίας. Ένα ανακληθέν κλειδί γίνεται άγνωστο τη στιγμή της ανάκλησής του.
Η διόρθωση. Ελέγξτε ότι η κεφαλίδα πράγματι φεύγει (οι proxies την αφαιρούν ενίοτε), ότι το κλειδί ξεκινά με vgk_ και ότι δεν έχει ανακληθεί από την κονσόλα του γραφείου. Επειδή το μυστικό εμφανίζεται μόνο κατά τη δημιουργία, ένα χαμένο κλειδί αντικαθίσταται, δεν ανακτάται.
Ληγμένο κλειδί
Κάθε κλειδί λήγει ένα έτος μετά τη δημιουργία — η ημερομηνία expire_le είναι ορατή στην κονσόλα του γραφείου από την πρώτη μέρα. Το 401 λήξης είναι ρητό: λέει ότι το κλειδί υπήρξε και δεν είναι πλέον έγκυρο.
Η διόρθωση. Δημιουργήστε νέο κλειδί, μεταφέρετε τις κλήσεις σας, ανακαλέστε το παλαιό. Προγραμματίστε αυτήν την αντικατάσταση στη λειτουργία σας αντί να την ανακαλύψετε: η ημερομηνία είναι γνωστή έναν χρόνο νωρίτερα.
Ανεπαρκές scope
Τα κλειδιά φέρουν lecture (ανάγνωση, η προεπιλογή) ή/και ecriture (εγγραφή). Ο χαρακτηρισμός ενός συμβάντος απαιτεί ecriture· ένα κλειδί μόνο για ανάγνωση λαμβάνει 403 ανεξαρτήτως πόρου.
Η διόρθωση. Δημιουργήστε κλειδί που φέρει το απαιτούμενο scope — και μόνο αυτό. Το ελάχιστο προνόμιο είναι εσκεμμένο: μια ενσωμάτωση που μόνο διαβάζει δεν έχει λόγο να κρατά κλειδί εγγραφής.
Δεν βρέθηκε — ή ανήκει σε άλλο γραφείο
Ένα 404 σημαίνει ότι ο πόρος δεν υπάρχει ή ανήκει σε άλλο γραφείο. Το API δεν διακρίνει ποτέ τις δύο περιπτώσεις: η διάκριση θα αποκάλυπτε τι υπάρχει αλλού. Ο διαχωρισμός επιβάλλεται σε επίπεδο βάσης δεδομένων, όχι μόνο στον κώδικα της εφαρμογής.
Η διόρθωση. Ελέγξτε το seq έναντι του ημερολογίου του γραφείου στο οποίο ανήκει το κλειδί (GET /api/v1/evenements). Αν ενσωματώνετε περισσότερα γραφεία, κάθε γραφείο έχει τα δικά του κλειδιά: ένα seq δεν ταξιδεύει μεταξύ γραφείων.
Υπέρβαση ορίου ρυθμού
60 αιτήματα ανά λεπτό ανά κλειδί, εξ ορισμού (παραμετροποιήσιμο ανά κλειδί). Η απόκριση φέρει Retry-After και τις κεφαλίδες X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Η διόρθωση. Σεβαστείτε το Retry-After — καμία άμεση επανάληψη. Το να φτάνετε στο όριο κατά το polling είναι σχεδόν πάντα σημάδι πλήρους επανασάρωσης: ο δρομέας depuisSeq δεν ξαναδιαβάζει ποτέ ό,τι έχει ήδη διαβαστεί.
Η υπογραφή δεν επαληθεύεται στην πλευρά σας
Ο δέκτης σας πρέπει να επανυπολογίζει το v1 = HMAC-SHA256(secret, t + "." + body) από το ακατέργαστο σώμα που λάβατε, και να απορρίπτει κάθε t παλαιότερο των 5 λεπτών. Οι κλασικές αστοχίες: το σώμα επανασειριοποιήθηκε πριν την επαλήθευση (ένα αναδιαμορφωμένο JSON δεν έχει πλέον τα ίδια bytes), ρολόι που αποκλίνει πέραν της ανοχής, και μια αγνοημένη εναλλαγή — για 24 ώρες η κεφαλίδα φέρει ένα v1 ανά ακόμη-έγκυρο μυστικό, και πρέπει να αποδεχθείτε αν οποιοδήποτε ταιριάζει.
Η διόρθωση. Επαληθεύστε έναντι των ακατέργαστων bytes, συγχρονίστε το ρολόι σας (NTP), δοκιμάστε την επαλήθευσή σας κατά τη διάρκεια μιας εναλλαγής. Τα αποσπάσματα Node και Python στην τεκμηρίωση κάνουν ακριβώς αυτό — αντιγράψτε τα αντί να τα ξαναγράψετε.
Ένα συμβάν φτάνει δύο φορές
Η παράδοση είναι at-least-once, σε παρτίδες έως 100, με τη σειρά του ημερολογίου· ο δρομέας προχωρά μόνο με το δικό σας 2xx, παρτίδα προς παρτίδα. Μια αστοχία μετά τη λήψη αλλά πριν προχωρήσει ο δρομέας προκαλεί επαναπαράδοση — αυτό είναι το συμβόλαιο, όχι ελάττωμα.
Η διόρθωση. Το seq είναι το κλειδί ταυτοδυναμίας σας: επεξεργαστείτε κάθε ακολουθία ακριβώς μία φορά, και απαντήστε 2xx μόνο αφού αποθηκεύσετε. Ένα πρόωρο 2xx ακολουθούμενο από κατάρρευση είναι ο μόνος τρόπος να χαθεί συμβάν.
Το ημερολόγιο φαίνεται ελλιπές ή επαναλαμβάνεται
Το depuisSeq είναι αυστηρά αποκλειστικό: επιστρέφονται μόνο τα συμβάντα με μεγαλύτερο seq, ταξινομημένα αύξοντα, έως 500 ανά σελίδα. Η απόκριση επιστρέφει prochainSeq, που το ξαναπερνάτε ως έχει. Μια σελίδα μικρότερη από το limite σημαίνει το τέλος του ημερολογίου.
Η διόρθωση. Αποθηκεύετε το prochainSeq μεταξύ εκτελέσεων και μην το επανυπολογίζετε ποτέ μόνοι σας. Τα διπλότυπα σημαίνουν ότι επανεκκινήσατε από πολύ παλαιό δρομέα· τα κενά σημαίνουν ότι προσπεράσατε μια αποτυχημένη σελίδα χωρίς να την επαναλάβετε.
Παράμετρος εκτός σχήματος
Μια άγνωστη κατάσταση, μια διάθεση εκτός καταλόγου (planifie, traite, ecarte), ένα μη ακέραιο limite: η απόκριση κατονομάζει το προβληματικό πεδίο, και τίποτα άλλο — τα μηνύματα σφάλματος δεν μεταφέρουν ποτέ περιεχόμενο φακέλων.
Η διόρθωση. Η προδιαγραφή OpenAPI είναι η πηγή: οι απαριθμήσεις και τα όρια που δηλώνει είναι αυτά που επιβάλλει ο διακομιστής, αφού σερβίρεται από αυτόν.
Ανεπαρκές scope (API πόρων)
Τα endpoints πόρων (/clients, /dossiers, έγγραφα, screening, ειδοποιήσεις) απαιτούν λεπτομερές scope: clients:*, dossiers:*, pieces:*, criblage:* ή το ειδικό scope alertes:qualifier. Ένα κλειδί παλαιού τύπου lecture χορηγεί όλα τα scopes *:lecture και το ecriture όλα τα *:ecriture — όμως το alertes:qualifier δεν κληρονομείται ποτέ: ο χαρακτηρισμός μιας ειδοποίησης είναι πράξη υπεύθυνου στελέχους, που εκχωρείται επιλέγοντας αυτό το scope κατά τη δημιουργία του κλειδιού.
Η διόρθωση. Δημιουργήστε κλειδί που φέρει ακριβώς τα scopes που χρειάζεται η ενσωμάτωσή σας — και μόνο αυτά. Το detail της απόκρισης κατονομάζει το scope που λείπει.
Πόρος που δεν βρέθηκε — ή ανήκει σε άλλο γραφείο
Ίδιος κανόνας με το #cloisonnement, εφαρμοσμένος στους πόρους: ένας πελάτης, ένας φάκελος, ένα έγγραφο ή μια ειδοποίηση που δεν υπάρχει ή ανήκει σε άλλο γραφείο λαμβάνει το ίδιο 404. Το API δεν ξεχωρίζει ποτέ τις δύο περιπτώσεις.
Η διόρθωση. Ελέγξτε το αναγνωριστικό έναντι των λιστών του γραφείου στο οποίο ανήκει το κλειδί. Ένα αναγνωριστικό δεν ταξιδεύει ποτέ από ένα γραφείο σε άλλο.
Λείπει η κεφαλίδα Idempotency-Key
Κάθε POST δημιουργίας ή ενεργοποίησης (πελάτης, φάκελος, έγγραφο, screening, πραγματικοί δικαιούχοι) απαιτεί την κεφαλίδα Idempotency-Key: μια σταθερή συμβολοσειρά έως 200 χαρακτήρες, μία ανά λειτουργία. Η επανάληψη του ίδιου κλειδιού με το ίδιο σώμα επιστρέφει την ίδια απόκριση, χωρίς κανένα αποτέλεσμα — η προστασία σας από τα διπλότυπα σε περίπτωση δικτυακού συμβάντος.
Η διόρθωση. Δημιουργήστε το κλειδί πριν από την πρώτη απόπειρα (ένα UUID ανά επιχειρησιακή λειτουργία) και επαναχρησιμοποιήστε το αμετάβλητο σε κάθε επανάληψη της ίδιας λειτουργίας.
Κλειδί ταυτοδυναμίας που επαναχρησιμοποιήθηκε με διαφορετικό σώμα
Αυτό το Idempotency-Key έχει ήδη χρησιμοποιηθεί για διαφορετικό σώμα εντός των τελευταίων 24 ωρών. Το κλειδί επαναλαμβάνει μια απόκριση, δεν την αντικαθιστά ποτέ: η επαναχρησιμοποίησή του για νέα λειτουργία είναι σχεδόν πάντα σημάδι κλειδιού παραγόμενου από μετρητή ή αποκομμένη ημερομηνία.
Η διόρθωση. Νέο κλειδί για κάθε νέα λειτουργία. Μην παράγετε ποτέ το κλειδί από δεδομένα που επαναλαμβάνονται μεταξύ λειτουργιών.
Σφραγισμένος φάκελος: το μητρώο είναι παγωμένο
Η σφράγιση παγώνει την αλυσίδα ακεραιότητας του φακέλου — αυτή είναι η αποδεικτική του αξία. Ένας σφραγισμένος φάκελος δεν μπορεί πλέον να τροποποιηθεί, δεν δέχεται πλέον έγγραφα και δεν υποβάλλεται πλέον σε νέο screening μέσω αυτού του καναλιού. Μόνο ο χαρακτηρισμός ειδοποιήσεων παραμένει δυνατός: γράφεται εκτός αλυσίδας, η σφραγισμένη κεφαλή δεν μετακινείται ποτέ.
Η διόρθωση. Τίποτα προς «διόρθωση»: πρόκειται για εσκεμμένη αμεταβλητότητα. Αν πρέπει να αλλάξουν δεδομένα, αυτό είναι μια νέα ενέργεια δέουσας επιμέλειας στην εφαρμογή, όχι μετάλλαξη του σφραγισμένου φακέλου.
Μη αποδεκτή μορφή εγγράφου
Τα δικαιολογητικά δέχονται PDF, JPG, JPEG, PNG και WEBP — τις ίδιες μορφές με την εφαρμογή. Ο έλεγχος γίνεται στην επέκταση του υποχρεωτικού filename: ένα έγγραφο χωρίς έγκυρο όνομα αρχείου απορρίπτεται, ανεξαρτήτως περιεχομένου.
Η διόρθωση. Μετατρέψτε πριν την αποστολή (μια σάρωση TIFF ή HEIC μετατρέπεται σε PDF ή JPEG) και στείλτε το περιεχόμενο σε τυπικό base64 στο contenu, με type από τους σταθερούς κωδικούς a_doc_*.
Έγγραφο άνω των 6 MB
Το όριο ισχύει για το αποκωδικοποιημένο αρχείο (6 MB), όπως στην εφαρμογή και στην πύλη συλλογής. Επειδή το base64 προσθέτει ένα τρίτο επιβάρυνση κωδικοποίησης, το σώμα του αιτήματος δέχεται έως 9 MB.
Η διόρθωση. Συμπιέστε το έγγραφο (ένα έγχρωμο σαρωμένο PDF στα 300 dpi πέφτει σχεδόν πάντα κάτω από το όριο σε κλίμακα του γκρι) αντί να το τεμαχίσετε.
Μη διαθέσιμη πηγή screening
Καμία από τις οντότητες του φακέλου δεν μπόρεσε να ελεγχθεί έναντι των καταλόγων: η πηγή (ευρετήριο επίσημων καταλόγων ή πάροχος) δεν απάντησε. Το API αρνείται να καταλήξει σε συμπέρασμα — ένα «καθαρό» αποτέλεσμα πάνω σε νεκρή πηγή θα ήταν το χειρότερο δυνατό ψευδώς αρνητικό. Η αστοχία καταγράφεται στον φάκελο (erreurSource). Μια μερική διακοπή δεν παράγει αυτό το 502: η απόκριση 200 κρατά τις αντιστοιχίσεις των οντοτήτων που απάντησαν και κατονομάζει τις αποτυχημένες στο erreurSourceEntites.
Η διόρθωση. Επαναλάβετε την ίδια κλήση αργότερα, με το ίδιο Idempotency-Key: μόνο οι αποκρίσεις επιτυχίας απομνημονεύονται από την ταυτοδυναμία — η επανάληψη μετά από σφάλμα εκτελεί πραγματικό screening.
Αυτή η σελίδα θα εξελίσσεται μαζί με το API· οι υπάρχουσες άγκυρες, ωστόσο, δεν αλλάζουν ποτέ διεύθυνση — μπορείτε να τις αποθηκεύσετε στα αρχεία καταγραφής της λειτουργίας σας.