Każdy błąd objaśniony pod stałym adresem.
Ta strona to referencja operacyjna, nie materiał sprzedażowy. Każda klasa błędów API Connect ma tu stałą kotwicę; odpowiedzi błędów API będą wskazywać te adresy. Dostajesz prawdopodobną przyczynę i rozwiązanie — w tej kolejności. Powrót do dokumentacji dla deweloperów.
Brak klucza, klucz zniekształcony lub nieznany
API uwierzytelnia wyłącznie nagłówkiem Authorization: Bearer vgk_… — nigdy ciasteczkiem sesji. Odwołany klucz staje się nieznany w chwili odwołania.
Rozwiązanie. Sprawdź, czy nagłówek faktycznie wychodzi (proxy czasem go wycinają), czy klucz zaczyna się od vgk_ i czy nie został odwołany z konsoli kancelarii. Ponieważ sekret jest pokazywany tylko przy utworzeniu, zgubiony klucz się wymienia, a nie odzyskuje.
Wygasły klucz
Każdy klucz wygasa rok po utworzeniu — data expire_le jest widoczna w konsoli kancelarii od pierwszego dnia. 401 wygaśnięcia jest jednoznaczne: mówi, że klucz istniał i nie jest już ważny.
Rozwiązanie. Utwórz nowy klucz, przełącz wywołania, odwołaj stary. Zaplanuj tę wymianę w swoich operacjach, zamiast ją odkrywać: data jest znana z rocznym wyprzedzeniem.
Niewystarczające uprawnienia
Klucze niosą lecture (odczyt, domyślne) i/lub ecriture (zapis). Kwalifikacja zdarzenia wymaga ecriture; klucz tylko do odczytu otrzymuje 403 niezależnie od zasobu.
Rozwiązanie. Utwórz klucz z potrzebnym uprawnieniem — i tylko nim. Najmniejsze uprawnienia to zamysł: integracja, która tylko czyta, nie ma powodu trzymać klucza zapisu.
Nie znaleziono — albo należy do innej kancelarii
404 oznacza, że zasób nie istnieje albo należy do innej kancelarii. API nigdy nie rozróżnia tych dwóch przypadków: rozróżnienie zdradzałoby, co istnieje gdzie indziej. Rozdzielenie jest wymuszane na poziomie bazy danych, nie tylko w kodzie aplikacji.
Rozwiązanie. Sprawdź seq względem dziennika kancelarii, do której należy klucz (GET /api/v1/evenements). Jeśli integrujesz kilka kancelarii, każda ma własne klucze: seq nie podróżuje między kancelariami.
Przekroczony limit żądań
Domyślnie 60 żądań na minutę na klucz (możliwe do zmiany per klucz). Odpowiedź niesie Retry-After oraz nagłówki X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Rozwiązanie. Uszanuj Retry-After — bez natychmiastowego ponowienia. Uderzenie w limit podczas odpytywania to niemal zawsze znak pełnego ponownego skanu: kursor depuisSeq nigdy nie czyta ponownie tego, co już przeczytane.
Podpis nie weryfikuje się po Twojej stronie
Twój odbiornik musi przeliczyć v1 = HMAC-SHA256(secret, t + "." + body) z surowego otrzymanego body i odrzucić każde t starsze niż 5 min. Klasyczne wpadki: body ponownie zserializowane przed weryfikacją (przeformatowany JSON nie ma już tych samych bajtów), zegar dryfujący poza tolerancję oraz zignorowana rotacja — przez 24 h nagłówek niesie jedno v1 na każdy wciąż ważny sekret i trzeba zaakceptować, jeśli którekolwiek się zgadza.
Rozwiązanie. Weryfikuj na surowych bajtach, zsynchronizuj zegar (NTP), przetestuj swoją weryfikację podczas rotacji. Fragmenty Node i Python w dokumentacji robią dokładnie to — skopiuj je, zamiast pisać od nowa.
Zdarzenie przychodzi dwa razy
Dostarczanie działa w trybie at-least-once, w partiach po maksymalnie 100, w kolejności dziennika; kursor przesuwa się tylko po Twoim 2xx, partia po partii. Awaria po odbiorze, lecz przed przesunięciem kursora, powoduje ponowną dostawę — to kontrakt, nie usterka.
Rozwiązanie. seq to Twój klucz idempotencji: przetwórz każdą sekwencję dokładnie raz i odpowiadaj 2xx dopiero po utrwaleniu. Przedwczesne 2xx, po którym następuje crash, to jedyny sposób, żeby zgubić zdarzenie.
Dziennik wygląda na niekompletny albo się powtarza
depuisSeq jest ściśle wykluczający: zwracane są tylko zdarzenia o wyższym seq, posortowane rosnąco, maksymalnie 500 na stronę. Odpowiedź zwraca prochainSeq, do przekazania bez zmian. Strona krótsza niż limite oznacza koniec dziennika.
Rozwiązanie. Utrwalaj prochainSeq między uruchomieniami i nigdy nie wyliczaj go samodzielnie. Duplikaty oznaczają, że wystartowano od zbyt starego kursora; luki — że pominięto nieudaną stronę bez jej ponowienia.
Parametr poza schematem
Nieznany status, dyspozycja spoza listy (planifie, traite, ecarte), niecałkowite limite: odpowiedź wskazuje wadliwe pole i nic więcej — komunikaty błędów nigdy nie niosą treści spraw.
Rozwiązanie. Źródłem jest specyfikacja OpenAPI: deklarowane w niej enumeracje i granice to te, które serwer wymusza, bo sam ją serwuje.
Niewystarczające uprawnienia (API zasobów)
Endpointy zasobów (/clients, /dossiers, dokumenty, weryfikacja sankcyjna, alerty) wymagają uprawnień drobnoziarnistych: clients:*, dossiers:*, pieces:*, criblage:* lub dedykowanego uprawnienia alertes:qualifier. Starszy klucz lecture nadaje wszystkie uprawnienia *:lecture, a ecriture — wszystkie *:ecriture; lecz alertes:qualifier nie jest nigdy dziedziczone: kwalifikacja alertu to czynność osoby odpowiedzialnej, delegowana przez zaznaczenie tego uprawnienia przy tworzeniu klucza.
Rozwiązanie. Utwórz klucz z dokładnie tymi uprawnieniami, których potrzebuje Twoja integracja — i tylko nimi. Pole detail odpowiedzi wskazuje brakujące uprawnienie.
Zasób nieznaleziony — albo należy do innej kancelarii
Ta sama reguła co #cloisonnement, zastosowana do zasobów: klient, sprawa, dokument lub alert, który nie istnieje albo należy do innej kancelarii, dostaje ten sam 404. API nigdy nie rozróżnia tych dwóch przypadków.
Rozwiązanie. Sprawdź identyfikator względem listingów kancelarii, do której należy klucz. Identyfikator nigdy nie podróżuje z jednej kancelarii do drugiej.
Brak nagłówka Idempotency-Key
Każdy POST tworzący lub wyzwalający (klient, sprawa, dokument, weryfikacja sankcyjna, beneficjenci rzeczywiści) wymaga nagłówka Idempotency-Key: stabilnego ciągu do 200 znaków, jednego na operację. Ponowienie tego samego klucza z tym samym body zwraca tę samą odpowiedź, bez żadnego skutku — Twoja ochrona przed duplikatami przy incydencie sieciowym.
Rozwiązanie. Wygeneruj klucz przed pierwszą próbą (jeden UUID na operację biznesową) i używaj go bez zmian przy każdym ponowieniu tej samej operacji.
Klucz idempotencji użyty ponownie z innym body
Ten Idempotency-Key został już użyty dla innego body w ciągu ostatnich 24 h. Klucz odtwarza odpowiedź, nigdy jej nie nadpisuje: ponowne użycie go dla nowej operacji to niemal zawsze znak klucza wyprowadzonego z licznika albo z obciętej daty.
Rozwiązanie. Nowy klucz dla każdej nowej operacji. Nigdy nie wyprowadzaj klucza z danych, które powtarzają się między operacjami.
Zapieczętowana sprawa: rejestr jest zamrożony
Zapieczętowanie zamraża łańcuch integralności sprawy — na tym polega jej walor dowodowy. Zapieczętowanej sprawy nie można już edytować, nie przyjmuje ona dokumentów i nie jest już ponownie weryfikowana tym kanałem. Możliwa pozostaje wyłącznie kwalifikacja alertów: zapisywana jest off-chain, zapieczętowana głowica łańcucha nigdy się nie przesuwa.
Rozwiązanie. Nie ma czego „naprawiać”: to zamierzona niezmienność. Jeśli dane muszą się zmienić, jest to nowa operacja należytej staranności w aplikacji, a nie mutacja zapieczętowanej sprawy.
Nieakceptowany format dokumentu
Dokumenty przyjmowane są w formatach PDF, JPG, JPEG, PNG i WEBP — tych samych co w aplikacji. Kontrola dotyczy rozszerzenia obowiązkowego filename: dokument bez poprawnej nazwy pliku jest odrzucany, niezależnie od zawartości.
Rozwiązanie. Przekonwertuj przed wysłaniem (skan TIFF lub HEIC konwertuje się do PDF lub JPEG) i wyślij zawartość jako standardowe base64 w contenu, z type spośród stabilnych kodów a_doc_*.
Dokument powyżej 6 MB
Limit dotyczy pliku po zdekodowaniu (6 MB) — ten sam co w aplikacji i portalu zbierania dokumentów. Ponieważ base64 dodaje jedną trzecią narzutu kodowania, body żądania przyjmuje do 9 MB.
Rozwiązanie. Skompresuj dokument (kolorowy PDF ze skanu 300 dpi niemal zawsze schodzi poniżej limitu w skali szarości), zamiast go dzielić.
Źródło weryfikacji sankcyjnej niedostępne
Żadnego z podmiotów sprawy nie udało się sprawdzić na listach: źródło (indeks list oficjalnych lub dostawca) nie odpowiedziało. API odmawia konkluzji — raport „czysto” na martwym źródle byłby najgorszym możliwym fałszywym negatywem. Awaria jest odnotowywana w sprawie (erreurSource). Awaria częściowa nie wywołuje tego 502: odpowiedź 200 zachowuje trafienia podmiotów, które odpowiedziały, i wskazuje te nieudane w erreurSourceEntites.
Rozwiązanie. Ponów później to samo wywołanie, z tym samym Idempotency-Key: idempotencja zapamiętuje wyłącznie odpowiedzi zakończone sukcesem — ponowienie po błędzie uruchamia rzeczywistą weryfikację sankcyjną.
Ta strona będzie ewoluować wraz z API; istniejące kotwice jednak nigdy nie zmieniają adresu — możesz je zapisywać w swoich logach operacyjnych.