Як правильно читати коди помилок KSeF у Польщі?
Кожне повідомлення шлюзу KSeF містить три шари: статус HTTP, exceptionCode та статус фактури. Правильне розшифрування цих параметрів дозволяє швидко визначити, чи проблема є технічною помилкою валідації XML, чи потребує залучення бухгалтера.
Шлюз KSeF (Krajowy System e-Faktur — польська національна система е-фактур) відповідає номером і одним реченням. А ви в ту саму хвилину маєте обрати одне з трьох: виправити XML, повторити запит або передати справу бухгалтеру. Три різні рішення, три різні витрати, три різні терміни.
За чинним законом штрафи за ст. 106ni закону про VAT діють з 1 січня 2027 року. 16 вересня 2026 року Міністерство фінансів оголосило про їх перенесення на 1 січня 2028 року — це законопроєкт, ще не ухвалений, і він переносить лише штрафи, а не сам обовʼязок працювати в KSeF. Фактура, яка не потрапила до системи, перестає бути технічною проблемою і стає фінансовим ризиком. Для українського бізнесу в Польщі є ще один шар складності: більшість повідомлень шлюзу існує лише польською, і саме через це їх часто читають неправильно.
Ця стаття — мапа. Вона показує, з чого складається відповідь KSeF, що означає кожна група кодів, які коди можна просто повторити, і де закінчується робота програміста та починається робота бухгалтера. Повний перелік кодів публікує Міністерство фінансів у документації API; тут ми розбираємо ті, що трапляються найчастіше.
Повідомлення 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 |
Зверніть увагу: числа 410 і 415 зустрічаються також як статуси обробки фактури в сесії, а не як код HTTP відповіді — приклад нижче стосується саме такого статусу. Найдорожча помилка інтерпретації в цій таблиці — 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 ширший за цей перелік. Джерелом правди залишаються документація API на api.ksef.mf.gov.pl і посібник для інтеграторів CIRF/MF.
Той самий документ, дві різні відповіді: приклад із нашого впровадження
10 вересня 2026 року на тестовому середовищі Міністерства ми перевіряли фактури із вкладенням. Та сама фактура, надіслана інтерактивною сесією, поверталася зі статусом обробки 415 і повідомленням про неможливість надіслати фактуру з вкладенням. Та сама фактура в пакетній сесії — прийнята. І та сама інтерактивна сесія приймала цей документ без вузла вкладення.
Висновок незручний, але важливий: частина повідомлень не каже «документ поганий», вона каже «не цим каналом». Той, хто почав би з правок у XML, правив би коректний файл. Різницю між режимами описано в документації пакетної сесії.
Помилка не завжди означає, що фактури немає в системі
Найдорожчі помилки стаються по той бік межі — коли фактура вже має номер KSeF.
Прийняття документа шлюзом означає відповідність логічній структурі, і не більше. KSeF не перевіряє правильності розрахунку VAT, обґрунтованості операції чи арифметики. Фактура з неправильною ставкою пройде технічну валідацію без жодного повідомлення.
Практичний наслідок: документ, який отримав номер KSeF, не можна «відкликати» з вашої системи продажу. Залишається коригувальна фактура. Технічна корекція стосується лише фактури, виставленої в режимі offline, яку KSeF відхилив, — документ з номером KSeF нею не виправити. Це вже бухгалтерське рішення, а не інтеграційне, і саме тому третій шар повідомлення не можна пропускати.
Окрема пастка — дублікати. KSeF розпізнає їх за комбінацією даних продавця, типу фактури та номера документа й утримує унікальність роками. Повторне надсилання «про всяк випадок» не є нейтральною дією.
Чек-лист: що зафіксувати за кожної помилки
Статус HTTP відповіді.
exceptionCodeі повний текстexceptionDescription.referenceNumberоперації (сесії, заявки, експорту).traceIdз відповіді.Середовище: тестове чи продакшн.
Статус фактури: чи надано номер KSeF.
Позначку часу в UTC — при лімітах і сесіях вирішує секунда.
Ці сім полів перетворюють «у нас не працює» на звернення, яке можна розглянути. Порядок звернень описано на сторінці підтримки для інтеграторів.
Підсумок
Коди помилок KSeF виглядають як суто технічна тема, але вирішують бухгалтерські питання: чи фактура існує, чи дотримано термін, чи потрібна корекція. Трьох шарів відповіді, мапи груп кодів і семи полів чек-листа достатньо, щоб перестати вгадувати.
Biurko перекладає 28 найпоширеніших кодів шлюзу одним зрозумілим реченням і однією підказаною дією, решту показує текстом Міністерства фінансів, а надсилання після тимчасових збоїв повторює автоматично (до трьох спроб, а після 429 чекає час, який назвав шлюз). Спробуйте Biurko — кожна нова фірма отримує 14 днів тарифу TEAM без картки — і подивіться, як виглядає відправлення до 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, але містить помилку? Видалити або перезаписати її не можна. Шлях — коригувальна фактура; технічна корекція стосується лише фактури, виставленої в режимі offline, яку KSeF відхилив.
Теги
Попередня стаття
Скільки коштує бухгалтер для JDG у Польщі та що обрати?
Наступна стаття
Як мінімальна зарплата 2027 року змінить ваш ZUS у Польщі?