Każdy błąd objaśniony pod stałym adresem.

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.

Ten sam 401 zawiera "motif": "fin_option_api", gdy klucz został zatrzymany, ponieważ API nie wchodzi już w zakres abonamentu kancelarii. Data tego zatrzymania została podana w e-mailu do administratorów kancelarii lub, w razie ich braku, na adres rozliczeniowy kancelarii, a następnie zapowiadana w nagłówku Sunset każdej odpowiedzi na zaakceptowane wywołanie (harmonogram w #cle-expiree). Bez motywu może też wynikać z zawieszonego abonamentu: zawieszenie natychmiast odcina klucze.

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. Przy "motif": "fin_option_api" ani nagłówek, ani klucz nie są przyczyną: administrator kancelarii pisze do nas na adres contact@vigilae.org, aby API wróciło do abonamentu, a ten sam klucz znów jest akceptowany, gdy tylko to nastąpi, aż do upływu jego własnego terminu ważności.

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.

Klucz API może też przestać być akceptowany przed tą datą, gdy API nie wchodzi już w zakres abonamentu kancelarii. Zatrzymanie następuje wtedy co najmniej 30 dni po pierwszym e-mailu, w dniu podanym w drugim e-mailu, wysłanym co najmniej 7 dni wcześniej; oba trafiają do administratorów kancelarii lub, w razie ich braku, na adres rozliczeniowy kancelarii. Gdy tylko zostanie ustalona, ta data jest widoczna w konsoli kancelarii (pole coupure_le w GET /connect/cles), a każda odpowiedź na zaakceptowane wywołanie zapowiada ją w nagłówku Sunset, dopóki nie nadejdzie. Po tej dacie wywołanie otrzymuje 401 opisany w #authentification, z "motif": "fin_option_api"; jeśli API wróci do abonamentu, klucz znów jest akceptowany, aż do upływu jego własnego terminu ważności.

Rozwiązanie. Utwórz nowy klucz, przełącz wywołania, odwołaj stary. W przypadku klucza API trzeba jednak, by API nadal wchodziło w zakres abonamentu kancelarii: bez niego konsola odmawia utworzenia klucza. Zaplanuj tę wymianę w swoich operacjach, zamiast ją odkrywać.

Niewystarczające uprawnienia

Klucze niosą uprawnienia zaznaczone przy ich tworzeniu: ogólne lecture (odczyt, domyślne) i ecriture (zapis) albo drobne, według zasobu (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Dziedziczenie idzie po przyrostku, tylko w jedną stronę: lecture pokrywa każde *:lecture, ecriture każde *:ecriture — odwrotnie nigdy; drobne uprawnienie otwiera wyłącznie siebie.

Sześć uprawnień wypada poza tę parę i nie dziedziczy się z żadnego klucza ogólnego: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kwalifikacja zdarzenia, wydanie tokena osadzenia, odczyt niekorzystnej prasy przy sprawie albo oceny prowadzenia sprawy nigdy nie wynika z ogólnego prawa odczytu: każde zaznacza się osobno.

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, a szeroki klucz nigdy nie zastąpi uprawnienia, którego nie oddelegowano wprost.

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.

To konto już istnieje

POST /scim/v2/Users na userName już założony dla tej kancelarii zwraca 409 z scimType: uniqueness. Unikalność zapewnia ograniczenie bazy danych, a nie pamięć podręczna: dwa równoczesne utworzenia nie mogą dać dwóch kont.

Rozwiązanie. Traktuj 409 jako idempotentne powodzenie, nie jako błąd: odczytaj konto przez ?filter=userName eq "…" i kontynuuj ze zwróconym identyfikatorem. Konektor, który ponawia w pętli po 409, nigdy nie utworzy nic więcej.

To konto jest poza zasięgiem katalogu

Katalog nie może ani obniżyć roli, ani wyłączyć konta niosącego uprawnienia administracyjne kancelarii: żądanie jest odrzucane z scimType: mutability i zapisywane w dzienniku. Bez tej granicy konektor przejmujący adres osoby odpowiedzialnej za zgodność zamknąłby kancelarię przed tym, kto za nią odpowiada.

Rozwiązanie. Usuń tę osobę z synchronizowanego zakresu albo zmień jej rolę w Vigilae. Odmowa dotyczy tylko tego konta: reszta partii jest stosowana normalnie.

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.

Pole, którego wartość jest zbyt długa: Obywatelstwo

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.

Inna próba z tym kluczem jeszcze trwa

Dwa żądania z tym samym Idempotency-Key dotarły razem: pierwsze się wykonuje, drugie zostaje odrzucone przed jakimkolwiek skutkiem. To właśnie ta odmowa zapobiega duplikatowi. Typowy przypadek: proxy zwraca 502 lub 504, gdy serwer jeszcze pracuje, a Twój klient ponawia żądanie. Nagłówek Retry-After podaje, po ilu sekundach je ponowić.

Rozwiązanie. Ponów to samo żądanie, bez zmian, z tym samym kluczem, po ogłoszonym czasie: otrzymasz odpowiedź pierwszej próby. Nigdy nie twórz nowego klucza, aby „odblokować” — to stworzyłoby właśnie duplikat, któremu klucz zapobiega.

Środowisko testowe: limit wyczerpany

Środowisko testowe ma stałe limity: 200 kart klientów, 50 spraw i 40 dokumentów na sprawę. Utworzenie lub przesłanie dokumentu, które przekroczyłoby którykolwiek z nich, zostaje odrzucone przed jakimkolwiek zapisem, a odmowa wskazuje, który to limit: pola ressource, quota i courant podają zasób, pułap i stan licznika w chwili odmowy. Z dwóch równoczesnych utworzeń o ostatnie miejsce przechodzi tylko jedno. Edycja istniejącej karty lub sprawy niczego nie zużywa.

Rozwiązanie. Te limity nie podlegają negocjacji, a ponowienie żądania przyniesie tę samą odmowę. Zresetuj środowisko testowe w swojej przestrzeni — wraca ono wtedy do danych demonstracyjnych — albo wykup abonament: te limity dotyczą wyłącznie środowisk testowych.

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.

Sprawa zamknięta: stosunki gospodarcze zostały zakończone

Relacja została zamknięta w aplikacji: sprawa nie przyjmuje już zapisów przez API — ani edycji, ani dokumentu, ani weryfikacji sankcyjnej, ani beneficjentów rzeczywistych. Odczyty pozostają otwarte: zamkniętą sprawę można przeglądać i eksportować przez cały okres przechowywania.

Rozwiązanie. Ponowne otwarcie relacji to czynność człowieka, zapisana w dzienniku, w aplikacji; API nie zrobi tego za Ciebie. Jeśli operacja jest nowa, otwórz nową sprawę, zamiast wskrzeszać starą.

Sprawa usunięta: dane zostały skasowane

Okres przechowywania upłynął i dane sprawy zostały skasowane. Pozostaje wyłącznie ślad audytowy, który poświadcza, że sprawa istniała i że została usunięta we wskazanym dniu; nie przyjmuje on już żadnego zapisu.

Rozwiązanie. Nie ma czego naprawiać ani ponawiać: usunięcie jest ostateczne i zamierzone. Identyfikator usuniętej sprawy przechowywany w Twoich systemach jest historią, nigdy celem zapisu.

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ą.

Widżety osadzone nie są włączone na tej instancji

Mint POST /api/v1/embed/jetons opiera się na źródłach zadeklarowanych dla Twojej kancelarii — to ta lista steruje CSP frame-ancestors osadzonego shellu. Ten 501 mówi, że wywołana instancja nie ma tego magazynu: powierzchnia embed jest tam nieaktywna z samej konstrukcji i mówi o tym wprost, zamiast wydać token, którego żadne źródło nigdy nie mogłoby wyświetlić. Nie mylić z 400 zwracanym kancelarii, której źródła nie są jeszcze zadeklarowane.

Rozwiązanie. Ten 501 dotyczy instancji, nie Twojego żądania. Na vigilae.org administrator Twojej kancelarii sam deklaruje źródła, na ekranie „Integracje i bezpieczeństwo” (ramka w sekcji widżetów mówi gdzie); następnie powtórz to samo wywołanie. Nic do zmiany w Twoim kodzie: żądanie było poprawne, instancja nie była gotowa.

Powierzchnia niedostępna w tym wdrożeniu

Dwa podstawowe odczyty — GET /api/v1/dossiers/{id}/origine-fonds i GET /api/v1/dossiers/{id}/exigences — opierają się na magazynach, których nie nosi każda instancja. Gdy jednego brakuje, API to mówi, zamiast podać pustą listę: „nie ma nic do zgłoszenia” i „nic nie zostało odczytane” to fakty przeciwstawne, a ich pomylenie sprawiłoby, że sprawa, do której nikt nie zajrzał, uchodziłaby za sprawę bez zastrzeżeń. To 501 mówi o wywołanej instancji, nigdy o Twoim żądaniu ani o sprawie.

Rozwiązanie. Nie powtarzaj wywołania w pętli: nic się nie zmieni, dopóki instancja nie będzie nosić tego magazynu. Traktuj ten kod jako „dane tu niedostępne” i przede wszystkim nie licz go jako zera na swoich pulpitach — właśnie tak brak pomiaru staje się złą liczbą. Na vigilae.org oba odczyty są obsługiwane; przy wdrożeniu dedykowanym rozbudowa magazynu należy do Twojego operatora.