Шлюз KSeF (Krajowy System e-Faktur — польська національна система е-фактур) відповідає номером і одним реченням. А ви в ту саму хвилину маєте обрати одне з трьох: виправити XML, повторити запит або передати справу бухгалтеру. Три різні рішення, три різні витрати, три різні терміни.
Перехідний період без санкцій закінчується 31 грудня 2026 року. Від 1 січня 2027 року фактура, яка не потрапила до системи, перестає бути технічною проблемою і стає фінансовим ризиком. Для українського бізнесу в Польщі є ще один шар складності: більшість повідомлень шлюзу існує лише польською, і саме через це їх часто читають неправильно.
Ця стаття — мапа. Вона показує, з чого складається відповідь KSeF, що означає кожна група кодів, які коди можна просто повторити, і де закінчується робота програміста та починається робота бухгалтера. Повний каталог — 133 повідомлення з поясненням і рекомендованою дією — у Словнику помилок KSeF.
Повідомлення KSeF має три шари, а не один
Номер помилки без контексту марний. Той самий 21405 сьогодні означає помилку в параметрі запиту, а завтра — неправильно змаплене поле в обліковій системі. Тому кожну відповідь читають на трьох рівнях:
Статус HTTP — чи шлюз узагалі прийняв запит.
exceptionCodeіexceptionDescription— конкретна причина з боку KSeF.Статус фактури або сесії — чи документ уже отримав номер KSeF, чи його в системі ще немає.
Лише разом вони відповідають на питання, чия це проблема. Перші два шари — це інтеграція. Третій — бухгалтерія, бо саме там вирішують, чи потрібна коригувальна фактура.
Ще два ідентифікатори варто логувати завжди: referenceNumber операції та traceId відповіді. Без них звернення до Ministerstwo Finansów або до постачальника ПЗ — це розповідь, а не звернення.
Мапа груп кодів: що каже початок номера
Нумерація KSeF 2.0 не випадкова. Перші цифри вказують на підсистему, яка відхилила запит, — цього достатньо, щоб за кілька секунд віддати справу правильній людині.
Група Сфера Хто виправляє 9xxx підпис і авторизаційний документ інтегратор 211xx автентифікація, сесії, отримання фактур, експорт інтегратор 212xx пакетна відправка та її частини інтегратор 213xx авторизація та токени доступу адміністратор у фірмі 214xx валідація документа та вхідних даних інтегратор або той, хто виставляє фактуру 250xx сертифікати KSeF адміністратор у фірмі 260xx токени KSeF адміністратор у фірмі
Практичне правило: усе, що нижче за 214xx, — це зазвичай конфігурація, а не фактура. Правити документ у відповідь на помилку автентифікації — найпоширеніший спосіб змарнувати годину.
Статуси HTTP: перше розгалуження
Статус Значення Дія 400 некоректний запит або помилка валідації вхідних даних читайте exceptionCode і список errors у відповіді 401 немає коректної автентифікації токен, сертифікат, чинність сесії 403 бракує повноважень або недозволений контекст контекст NIP (польський податковий номер) і обсяг повноважень 410 операція втратила чинність і вже недоступна почніть процес спочатку 415 тип операції недопустимий у цьому режимі відправлення змініть режим (приклад нижче) 429 перевищено ліміт запитів до API Retry-After, черга, backoff — фактуру не чіпайте 5xx збій на боці інфраструктури KSeF збережіть traceId, повторіть за процедурою retry
Найдорожча помилка інтерпретації в цій таблиці — 429. Його легко сприйняти як відмову в прийнятті документа й почати «виправляти» коректну фактуру. Ліміти описані в документації CIRF/MF.
Найчастіші коди та що з ними робити
Підпис і авторизаційний документ (9xxx)
Код Повідомлення Дія 9101 Некоректний документ перевірте документ, використаний у процесі підпису 9102 Немає підпису обовʼязковий підпис не додано 9103 Перевищено кількість дозволених підписів перевірте кількість підписів для цього типу документа
Сесії, фактури та експорт (211xx)
Код Повідомлення Дія 21111 Некоректний авторизаційний challenge challenge, шифрування та час в автентифікації 21115 Некоректний сертифікат чинність і відповідність вимогам KSeF 21117 Некоректний ідентифікатор субʼєкта для типу контексту NIP не відповідає обраному типу контексту 21155 Перевищено кількість фактур у сесії закрийте сесію та відкрийте нову 21157 Некоректний розмір частини пакета оголошений розмір ≠ фактичний файл 21161 Перевищено кількість частин пакета перезберіть пакет 21164 Фактури із зазначеним ідентифікатором не існує номер KSeF, контекст субʼєкта, права на завантаження 21165 Фактура ще недоступна це не помилка — зачекайте й повторіть запит 21166 Технічна корекція недоступна найімовірніше, її вже оброблено 21167 Статус фактури не дозволяє технічної корекції справа для бухгалтерії, не для інтегратора 21173 Немає сесії із зазначеним referenceNumber номер або середовище (тест чи прод) 21175 Результату запиту не існує референс експорту або вичерпано час доступності результату 21178 UPO за вказаними критеріями не знайдено UPO (офіційне підтвердження отримання) зʼявляється після закриття сесії 21180 Статус сесії не дозволяє операції сесію закрито або скасовано 21181 Некоректний запит на експорт фактур критерії та контекст експорту 21182 Досягнуто ліміту одночасних експортів зменште кількість паралельних експортів 21183 Діапазон фільтрації поза доступним обсягом даних діапазон і тип дати
Пакетна відправка (212xx)
Код Повідомлення Дія 21205 Пакет не може бути порожнім надіслано не всі оголошені частини 21208 Перевищено час очікування upload або finish сесію могло бути скасовано — повторіть процес 21217 Некоректне кодування символів UTF-8 без BOM
Автентифікація та авторизація (213xx)
Код Повідомлення Дія 21301 Немає авторизації токен анульовано або автентифікацію не завершено 21304 Немає автентифікації операції з таким referenceNumber у цьому середовищі не існує 21308 Спроба скористатися авторизаційними методами померлої особи потрібно змінити спосіб автентифікації субʼєкта
Валідація документа та даних (214xx)
Код Повідомлення Дія 21401 Документ не відповідає схемі XSD класична «помилка фактури»: структура FA(3), обовʼязкові поля, кодування 21402 Некоректний розмір файлу оголошений розмір ≠ фактична довжина вмісту 21403 Некоректний хеш файлу спосіб обчислення хешу 21405 Помилка валідації вхідних даних читайте деталі, а не номер — сам код нічого не каже 21406 Конфлікт підпису й типу автентифікації метод автентифікації проти типу сертифіката 21418 Некоректний формат токена продовження не редагуйте токен пагінації вручну 21470 Невідомий або відкликаний ідентифікатор ключа завантажте актуальний публічний ключ для свого середовища
Сертифікати та токени (250xx, 260xx)
Код Повідомлення Дія 25001 Неможливо отримати дані для CSR цим способом автентифікації змініть спосіб автентифікації 25002 Неможливо подати сертифікаційну заявку цим способом те саме 25003 Дані в CSR не збігаються з автентифікаційним вектором дані субʼєкта в CSR 25004 Некоректний формат або підпис CSR формат заявки та алгоритм підпису 25005 Сертифікаційної заявки з таким номером не існує номер референції та середовище 25006 Досягнуто ліміту поданих заявок упорядкуйте заявки 25007 Досягнуто ліміту наявних сертифікатів анулюйте невикористовувані 25010 Некоректний тип або довжина ключа вимоги з документації сертифікатів 25011 Некоректний алгоритм підпису CSR алгоритм і хеш-функція 26001 Не можна надати токену повноважень, яких не має субʼєкт спершу повноваження субʼєкта 26002 Не можна згенерувати токен для поточного типу контексту токен лише в дозволеному контексті
Каталог KSeF 2.0 ширший за цей перелік. Усі 133 позиції разом із контрактом OpenAPI зібрані в Словнику помилок KSeF, а джерелом правди залишаються документація API на api.ksef.mf.gov.pl і посібник для інтеграторів CIRF/MF.
Той самий документ, дві різні відповіді: приклад із нашого впровадження
10 вересня 2026 року на тестовому середовищі Міністерства ми перевіряли фактури із вкладенням. Та сама фактура, надіслана інтерактивною сесією, поверталася зі статусом 415 і повідомленням про неможливість надіслати фактуру з вкладенням. Та сама фактура в пакетній сесії — прийнята. І та сама інтерактивна сесія приймала цей документ без вузла вкладення.
Висновок незручний, але важливий: частина повідомлень не каже «документ поганий», вона каже «не цим каналом». Той, хто почав би з правок у XML, правив би коректний файл. Різницю між режимами описано в документації пакетної сесії.
Помилка не завжди означає, що фактури немає в системі
Найдорожчі помилки стаються по той бік межі — коли фактура вже має номер KSeF.
Прийняття документа шлюзом означає відповідність логічній структурі, і не більше. KSeF не перевіряє правильності розрахунку VAT, обґрунтованості операції чи арифметики. Фактура з неправильною ставкою пройде технічну валідацію без жодного повідомлення.
Практичний наслідок: документ, який отримав номер KSeF, не можна «відкликати» з вашої системи продажу. Залишається коригувальна фактура або — у вузькому переліку випадків, передбачених приписами, — технічна корекція. Це вже бухгалтерське рішення, а не інтеграційне, і саме тому третій шар повідомлення не можна пропускати.
Окрема пастка — дублікати. KSeF розпізнає їх за комбінацією даних продавця, типу фактури та номера документа й утримує унікальність роками. Повторне надсилання «про всяк випадок» не є нейтральною дією.
Чек-лист: що зафіксувати за кожної помилки
Статус HTTP відповіді.
exceptionCodeі повний текстexceptionDescription.referenceNumberоперації (сесії, заявки, експорту).traceIdз відповіді.Середовище: тестове чи продакшн.
Статус фактури: чи надано номер KSeF.
Позначку часу в UTC — при лімітах і сесіях вирішує секунда.
Ці сім полів перетворюють «у нас не працює» на звернення, яке можна розглянути. Порядок звернень описано на сторінці підтримки для інтеграторів.
Підсумок
Коди помилок KSeF виглядають як суто технічна тема, але вирішують бухгалтерські питання: чи фактура існує, чи дотримано термін, чи потрібна корекція. Трьох шарів відповіді, мапи груп кодів і семи полів чек-листа достатньо, щоб перестати вгадувати.
Biurko перекладає повідомлення шлюзу одним зрозумілим реченням і однією підказаною дією, а повтори після 429 та 5xx відбуваються без вашої участі. Спробуйте Biurko 14 днів безкоштовно на biurko.io — і подивіться, як виглядає відправлення до KSeF, у якому не треба читати номери.
FAQ
Що означає помилка 21401 у KSeF? Документ не відповідає схемі XSD. На практиці це найчастіше структура FA(3), незаповнене обовʼязкове поле або кодування, відмінне від UTF-8 без BOM. Сам номер не вказує поле — його вказує повідомлення валідатора, повернуте разом із кодом.
Чи означає помилка 429, що фактуру відхилено? Ні. Це перевищення ліміту запитів до API, і стосується воно лише інтеграції. З фактурою все гаразд. Рішення — заголовок Retry-After, черга запитів і експоненційний backoff, а не зміни в документі.
Якщо KSeF прийняв фактуру, чи означає це, що вона правильна? Ні. Система перевіряє відповідність логічній структурі та технічну коректність файлу. Вона не перевіряє розрахунку VAT чи арифметики. Фактура зі змістовною помилкою може отримати номер KSeF і потребувати корекції пізніше.
Де офіційний перелік кодів помилок KSeF? Джерело правди — контракт OpenAPI і документація API 2.0 на api.ksef.mf.gov.pl, а також репозиторій CIRF/MF із посібником для інтеграторів і changelog, у якому Міністерство публікує нові коди.
Що робити, якщо фактура вже має номер KSeF, але містить помилку? Видалити або перезаписати її не можна. Стандартний шлях — коригувальна фактура; технічна корекція доступна лише у випадках, передбачених приписами, і лише для певних статусів документа.