Всяка грешка, обяснена на стабилен адрес.
Тази страница е оперативен справочник, а не реклама. Всеки клас грешки на Connect API има тук постоянна котва; отговорите за грешка на API-я ще сочат към тези адреси. Получавате вероятната причина и поправката — в този ред. Обратно към документацията за разработчици.
Липсващ, неправилно оформен или непознат ключ
API-ят удостоверява единствено чрез заглавката Authorization: Bearer vgk_… — никога чрез сесийна бисквитка. Отменен ключ става непознат в мига на отмяната.
Поправката. Проверете дали заглавката наистина заминава (прокситата понякога я премахват), дали ключът започва с vgk_ и дали не е бил отменен от конзолата на кантората. Тъй като тайната се показва само при създаването, изгубен ключ се заменя, а не се възстановява.
Изтекъл ключ
Всеки ключ изтича една година след създаването — датата expire_le е видима в конзолата на кантората от първия ден. 401 при изтичане е изричен: казва, че ключът е съществувал и вече не е валиден.
Поправката. Създайте нов ключ, прехвърлете заявките си, отменете стария. Планирайте тази подмяна в операциите си, вместо да я откривате: датата е известна година напред.
Недостатъчен обхват
Ключовете носят lecture (четене, по подразбиране) и/или ecriture (запис). Квалифицирането на събитие изисква ecriture; ключ само за четене получава 403 независимо от ресурса.
Поправката. Създайте ключ с необходимия обхват — и само с него. Минималните привилегии са съзнателен избор: интеграция, която само чете, няма причина да държи ключ за запис.
Не е намерено — или е на друга кантора
404 означава, че ресурсът не съществува или принадлежи на друга кантора. API-ят никога не разграничава двата случая: разграничаването би разкрило какво съществува другаде. Изолацията се налага на ниво база данни, а не само в приложния код.
Поправката. Проверете seq срещу журнала на кантората, на която принадлежи ключът (GET /api/v1/evenements). Ако интегрирате няколко кантори, всяка кантора има свои ключове: един seq не пътува между кантори.
Превишен дебит
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 спецификацията е източникът: изброяванията и границите, които тя декларира, са тези, които сървърът налага, тъй като тя се сервира от него.
Недостатъчен обхват (ресурсен 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 часа. Ключът преизпраща отговор, никога не презаписва: повторното му използване за нова операция почти винаги е знак за ключ, извлечен от брояч или от отрязана дата.
Поправката. Нов ключ за всяка нова операция. Никога не извличайте ключа от данни, които се повтарят между операциите.
Запечатана преписка: регистърът е замразен
Запечатването замразява веригата на целостта на преписката — в това е доказателствената ѝ стойност. Запечатана преписка вече не може да бъде редактирана, вече не получава документи и вече не се проверява повторно по този канал. Възможно остава само квалифицирането на сигнали: то се записва извън веригата; запечатаният връх никога не помръдва.
Поправката. Няма какво да се „поправя“: това е съзнателна неизменяемост. Ако данни трябва да се променят, това е нова операция по надлежния контрол в приложението, а не мутация на запечатаната преписка.
Неприет формат на документ
Придружаващите документи приемат 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: идемпотентността запомня само отговорите за успех — повторение след грешка изпълнява истинска проверка.
Тази страница ще се развива заедно с API-я; съществуващите котви обаче никога не сменят адреса си — можете да ги съхранявате в оперативните си журнали.