Всяка грешка, обяснена на стабилен адрес.

Липсващ, неправилно оформен или непознат ключ

API-ят удостоверява единствено чрез заглавката Authorization: Bearer vgk_… — никога чрез сесийна бисквитка. Отменен ключ става непознат в мига на отмяната.

Същият 401 носи "motif": "fin_option_api", когато ключът е прекратен, защото API вече не е част от абонамента на кантората. Датата на прекратяването е посочена в имейл до администраторите на кантората или, ако няма такива, до нейния адрес за фактуриране, а след това е обявявана в заглавката Sunset на всеки отговор на приета заявка (графикът е в #cle-expiree). Без мотив той може да се дължи и на спрян абонамент: спирането прекъсва ключовете незабавно.

Поправката. Проверете дали заглавката наистина заминава (прокситата понякога я премахват), дали ключът започва с vgk_ и дали не е бил отменен от конзолата на кантората. Тъй като тайната се показва само при създаването, изгубен ключ се заменя, а не се възстановява. При "motif": "fin_option_api" причината не е нито в заглавката, нито в ключа: администраторът на кантората ни пише на contact@vigilae.org, за да бъде API отново включен в абонамента, и същият ключ отново се приема веднага щом това стане, до изтичането на собствения му срок.

Изтекъл ключ

Всеки ключ изтича една година след създаването — датата expire_le е видима в конзолата на кантората от първия ден. 401 при изтичане е изричен: казва, че ключът е съществувал и вече не е валиден.

API ключ може да престане да бъде приеман и преди тази дата, когато API вече не е част от абонамента на кантората. Прекратяването настъпва тогава поне 30 дни след първи имейл, на датата, посочена във втори имейл, изпратен поне 7 дни предварително; и двата се изпращат до администраторите на кантората или, ако няма такива, до нейния адрес за фактуриране. Щом бъде определена, тази дата се вижда в конзолата на кантората (полето coupure_le на GET /connect/cles), а всеки отговор на приета заявка я обявява в заглавката Sunset, докато настъпи. След тази дата заявката получава 401, описан в #authentification, с "motif": "fin_option_api"; ако API отново бъде включен в абонамента, ключът отново се приема, до изтичането на собствения му срок.

Поправката. Създайте нов ключ, прехвърлете заявките си, отменете стария. За API ключ е нужно API все още да е част от абонамента на кантората: без него конзолата отказва да създаде ключ. Планирайте тази подмяна в операциите си, вместо да я откривате.

Недостатъчен обхват

Ключовете носят обхватите, отметнати при създаването им: общите lecture (четене, по подразбиране) и ecriture (запис) или фини обхвати по ресурс (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Наследяването е по суфикс и само в едната посока: lecture покрива всяко *:lecture, ecriture — всяко *:ecriture; обратното никога не важи, финият обхват отваря само себе си.

Шест обхвата излизат извън тази двойка и не се наследяват от никакъв общ ключ: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Квалифицирането на събитие, издаването на токен за вграждане, четенето на неблагоприятната преса по една преписка или на оценка за водене никога не следва от общо право на четене: всеки се отмята отделно.

Поправката. Създайте ключ с необходимия обхват — и само с него. Минималните привилегии са съзнателен избор: интеграция, която само чете, няма причина да държи ключ за запис, а широкият ключ никога няма да замести обхват, който не е делегиран изрично.

Не е намерено — или е на друга кантора

404 означава, че ресурсът не съществува или принадлежи на друга кантора. API-ят никога не разграничава двата случая: разграничаването би разкрило какво съществува другаде. Изолацията се налага на ниво база данни, а не само в приложния код.

Поправката. Проверете seq срещу журнала на кантората, на която принадлежи ключът (GET /api/v1/evenements). Ако интегрирате няколко кантори, всяка кантора има свои ключове: един seq не пътува между кантори.

Този профил вече съществува

POST /scim/v2/Users върху userName, вече създаден за тази кантора, връща 409 с scimType: uniqueness. Уникалността се държи от ограничение в базата данни, а не от кеш: две едновременни създавания не могат да породят два профила.

Поправката. Третирайте 409 като идемпотентен успех, а не като грешка: прочетете профила чрез ?filter=userName eq "…" и продължете с върнатия идентификатор. Конектор, който повтаря в цикъл при 409, никога няма да създаде нищо повече.

Този профил е извън обсега на указателя

Указателят не може нито да понижи, нито да деактивира профил с административни правомощия в кантората: заявката се отхвърля с scimType: mutability и се записва в дневника. Без това ограничение конектор, който възприеме адреса на отговорника по съответствието, би затворил кантората именно за онзи, който отговаря за нея.

Поправката. Извадете това лице от синхронизирания обхват или променете ролята му във Vigilae. Отказът засяга само този профил: останалата част от партидата се прилага нормално.

Превишен дебит

60 заявки в минута на ключ, по подразбиране (променимо за всеки ключ). Отговорът носи Retry-After и заглавките X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Поправката. Спазвайте Retry-After — без незабавен повторен опит. Удрянето на лимита при допитване почти винаги е знак за пълно повторно сканиране: курсорът depuisSeq никога не препрочита вече прочетеното.

Подписът не се потвърждава от ваша страна

Вашият приемник трябва да изчисли отново v1 = HMAC-SHA256(secret, t + "." + body) от суровото получено тяло и да отхвърля всеки t, по-стар от 5 мин. Класическите провали: тяло, пресериализирано преди проверката (преформатиран JSON вече няма същите байтове), часовник, отклонил се отвъд толеранса, и пренебрегната ротация — в продължение на 24 ч заглавката носи по един v1 за всяка все още валидна тайна и трябва да приемете, ако който и да е съвпада.

Поправката. Проверявайте срещу суровите байтове, синхронизирайте часовника си (NTP), изпробвайте проверката си по време на ротация. Извадките за Node и Python в документацията правят точно това — копирайте ги, вместо да ги пренаписвате.

Събитие пристига два пъти

Доставката е at-least-once, на партиди от най-много 100, по реда на журнала; курсорът напредва само при ваш 2xx, партида по партида. Провал след получаването, но преди курсорът да напредне, предизвиква повторна доставка — това е договорът, а не дефект.

Поправката. seq е вашият ключ за идемпотентност: обработвайте всяка последователност точно веднъж и отговаряйте 2xx едва след като сте записали трайно. Преждевременен 2xx, последван от срив, е единственият начин да изгубите събитие.

Журналът изглежда непълен или се повтаря

depuisSeq е строго изключващ: връщат се само събития с по-висок seq, сортирани възходящо, най-много 500 на страница. Отговорът връща prochainSeq, който подавате обратно без промяна. Страница, по-къса от limite, означава край на журнала.

Поправката. Съхранявайте prochainSeq между изпълненията и никога не го преизчислявайте сами. Дубликатите означават, че сте рестартирали от твърде стар курсор; пропуските — че сте прескочили провалена страница, без да я повторите.

Параметър извън схемата

Непознат статус, диспозиция извън списъка (planifie, traite, ecarte), нецелочислен limite: отговорът назовава проблемното поле и нищо друго — съобщенията за грешка никога не носят съдържание от преписки.

Поправката. OpenAPI спецификацията е източникът: изброяванията и границите, които тя декларира, са тези, които сървърът налага, тъй като тя се сервира от него.

Поле, чиято стойност е прекалено дълга: Гражданство

Отговорът назовава проблемното поле и нищо друго — съобщенията за грешка никога не носят съдържание от преписки.

Поправката. OpenAPI спецификацията е източникът: изброяванията и границите, които тя декларира, са тези, които сървърът налага, тъй като тя се сервира от него.

Недостатъчен обхват (ресурсен API)

Ресурсните крайни точки (/clients, /dossiers, документи, проверка за съответствие, сигнали) изискват фин обхват: clients:*, dossiers:*, pieces:*, criblage:* или специалния обхват alertes:qualifier. Заварен ключ lecture дава всички обхвати *:lecture, а ecriture — всички *:ecriture; но alertes:qualifier никога не се наследява: квалифицирането на сигнал е акт на отговорника, делегиран чрез отбелязване на този обхват при създаването на ключа.

Поправката. Създайте ключ с точно обхватите, от които вашата интеграция се нуждае — и само с тях. Полето detail в отговора назовава липсващия обхват.

Ресурсът не е намерен — или е на друга кантора

Същото правило като #cloisonnement, приложено към ресурсите: клиент, преписка, документ или сигнал, който не съществува или принадлежи на друга кантора, получава същия 404. API-ят никога не различава двата случая.

Поправката. Проверете идентификатора срещу списъците на кантората, на която принадлежи ключът. Идентификатор никога не пътува от една кантора към друга.

Липсва заглавка Idempotency-Key

Всеки POST за създаване или задействане (клиент, преписка, документ, проверка за съответствие, действителни собственици) изисква заглавката Idempotency-Key: стабилен низ от най-много 200 знака, по един за операция. Повторното подаване на същия ключ със същото тяло връща същия отговор, без ефект — вашата защита срещу дубликати при мрежов инцидент.

Поправката. Генерирайте ключа преди първия опит (по един UUID за бизнес операция) и го използвайте непроменен при всеки повторен опит на същата операция.

Ключ за идемпотентност, използван повторно с различно тяло

Този Idempotency-Key вече е бил използван за различно тяло през последните 24 часа. Ключът преизпраща отговор, никога не презаписва: повторното му използване за нова операция почти винаги е знак за ключ, извлечен от брояч или от отрязана дата.

Поправката. Нов ключ за всяка нова операция. Никога не извличайте ключа от данни, които се повтарят между операциите.

Друг опит с този ключ още се изпълнява

Две заявки с един и същ Idempotency-Key са пристигнали заедно: първата се изпълнява, втората е отказана преди всякакъв ефект. Именно този отказ предотвратява дубликата. Обичайният случай: прокси връща 502 или 504, докато сървърът още работи, и вашият клиент подава заявката отново. Заглавката Retry-After казва след колко секунди да я подадете отново.

Поправката. Подайте същата заявка, без промяна, със същия ключ, след обявеното изчакване: ще получите отговора на първия опит. Никога не създавайте нов ключ, за да „отблокирате“ — това би създало точно дубликата, който ключът избягва.

Тестова среда: квотата е достигната

Тестовата среда има фиксирани лимити: 200 клиентски картона, 50 преписки и 40 документа на преписка. Всяко създаване или качване, което би надхвърлило някой от тях, получава отказ преди какъвто и да е запис, а отказът посочва кой: полетата ressource, quota и courant носят ресурса, тавана и броя към момента на отказа. От две едновременни създавания за последното място минава само едното. Промяната на съществуващ клиентски картон или на съществуваща преписка не изразходва нищо от квотата.

Поправката. Тези квоти не подлежат на договаряне и ако подадете заявката отново, ще получите същия отказ. Нулирайте тестовата среда от вашия профил — тя започва отново от демонстрационните данни — или се абонирайте: тези квоти се прилагат само за тестови среди.

Запечатана преписка: регистърът е замразен

Запечатването замразява веригата на целостта на преписката — в това е доказателствената ѝ стойност. Запечатана преписка вече не може да бъде редактирана, вече не получава документи и вече не се проверява повторно по този канал. Възможно остава само квалифицирането на сигнали: то се записва извън веригата; запечатаният връх никога не помръдва.

Поправката. Няма какво да се „поправя“: това е съзнателна неизменяемост. Ако данни трябва да се променят, това е нова операция по надлежния контрол в приложението, а не мутация на запечатаната преписка.

Приключена преписка: деловите отношения са прекратени

Отношението е прекратено в приложението: преписката вече не приема записи през API — нито редакция, нито документ, нито проверка за съответствие, нито действителни собственици. Четенето остава отворено: приключена преписка се преглежда и изнася през целия срок на съхранение.

Поправката. Възобновяването на отношението е човешко действие, вписано в дневника, в приложението; API не го прави вместо вас. Ако операцията е нова, открийте нова преписка, вместо да съживявате старата.

Изтрита преписка: данните са заличени

Срокът на съхранение е изтекъл и данните на преписката са заличени. Остава само одитната следа, която удостоверява, че преписка е съществувала и че е изтрита на посочената дата; тя вече не приема никакъв запис.

Поправката. Няма какво да се поправя, нито да се подава отново: заличаването е окончателно и съзнателно. Идентификатор на изтрита преписка, запазен във вашите системи, е история, никога цел за запис.

Неприет формат на документ

Придружаващите документи приемат 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, почти винаги пада под ограничението в сива гама), вместо да го разделяте.

Недостъпен източник за проверка

Нито един от субектите на преписката не можа да бъде проверен срещу списъците: източникът (индексът на официалните списъци или доставчикът) не отговори. API-ят отказва да заключи — „чист“ доклад върху мъртъв източник би бил най-лошият възможен фалшив отрицателен резултат. Провалът се записва в преписката (erreurSource). Частичен отказ не поражда този 502: отговорът 200 запазва съвпаденията на субектите, които са отговорили, и назовава провалените в erreurSourceEntites.

Поправката. Повторете същата заявка по-късно, със същия Idempotency-Key: идемпотентността запомня само отговорите за успех — повторение след грешка изпълнява истинска проверка.

Вградени уиджети — неактивирани на тази инстанция

Mint POST /api/v1/embed/jetons разчита на произходите, декларирани за вашата кантора — именно този списък управлява CSP директивата frame-ancestors на вградения shell. Този 501 казва, че извиканата инстанция не носи това хранилище: повърхността за вграждане там е неактивна по конструкция и го казва, вместо да издаде токен, който никой произход не би могъл никога да покаже. Да не се бърка с 400, връщан на кантора, чиито произходи все още не са декларирани.

Поправката. Този 501 се отнася до инстанцията, не до вашата заявка. На vigilae.org администраторът на вашата кантора сам декларира произходите, в екран „Интеграции и сигурност“ (карето в раздела за уиджети казва къде); след което повторете същата заявка. Нищо за поправяне в кода ви: заявката беше наред, инстанцията не беше готова.

Повърхност, недостъпна в това внедряване

Две базови четения — GET /api/v1/dossiers/{id}/origine-fonds и GET /api/v1/dossiers/{id}/exigences — се опират на хранилища, които не всички инстанции носят. Когато едно липсва, API-ят го казва, вместо да върне празен списък: „няма какво да се отбележи“ и „нищо не е прочетено“ са противоположни факти, а смесването им би представило преписка, която никой не е поглеждал, за преписка без забележки. Този 501 се отнася до извиканата инстанция, никога до вашата заявка или до преписката.

Поправката. Не повтаряйте в цикъл: нищо няма да се промени, докато инстанцията не носи това хранилище. Третирайте кода като „данните не са налични тук“ и най-вече не го бройте за нула в таблата си — така липсата на измерване се превръща в грешна цифра. На vigilae.org и двете четения се обслужват; при специално внедряване надграждането на хранилището е задача на вашия оператор.