Baza wiedzy o serwisach administracji publicznej

API CRU zwraca dwa rodzaje błędów: techniczne (kody HTTP 4xx i 5xx dla całego żądania) oraz biznesowe (w odpowiedzi 200 OK, osobno dla każdej umowy w paczce).

Błędy techniczne – kody HTTP

• 400 – błędne dane wejściowe, na przykład niepoprawny JSON albo paczka większa niż 500 umów,
• 403 – brak nagłówka X-API-KEY, niepoprawny lub zablokowany klucz albo brak uprawnień,
• 404 – nie znaleziono zasobu,
• 429 – przekroczono limit wywołań (3 żądania na sekundę na klucz dla publikacji),
• 500 – błąd serwera.

Błąd techniczny ma pola code, message i details, na przykład code: JSON_PARSE_ERROR.

Jak czytać pole errors?

• klucz errors[“2”] oznacza błędy umowy z numerPorzadkowy = 2,
• w środku pole fields wskazuje ścieżkę błędnego pola, na przykład stronyUmowy[1].nip albo podstawoweDane.statusUmowy,
• pusty klucz “” oznacza błąd ogólny umowy, niezwiązany z konkretnym polem.

Najczęstsze błędy walidacji i ich przyczyny

• „wymagane jest przekazanie numeru NIP albo REGON” – polska strona bez identyfikatora,
• „należy przekazać tylko jeden identyfikator” – podano jednocześnie NIP i REGON,
• „nie należy przekazywać nazwy” – polska strona z polem nazwa (nazwa pochodzi z REGON),
• „nie należy przekazywać numeru REGON ani NIP” – strona zagraniczna z polskim identyfikatorem,
• „nie można wskazać rodzaju SU03” – jednostka publiczna z krajem innym niż PL,
• „dla pierwszej strony umowy nie należy przekazywać numeru NIP” – pierwsza strona ma mieć tylko rodzaj i regon,
• „należy uzupełnić komplet wymaganych pól adresowych” – niepełny adres podany ręcznie,
• „Nie znaleziono podmiotu w rejestrze REGON” – błędny numer albo podmiot nie istnieje,
• „REGON musi zawierać 9 lub 14 cyfr” – błędny format,
• „Pole jest wymagane” przy okresDo – podano okresOd bez okresDo.

Błąd CONFLICT przy REGON

Pojawia się, gdy dla jednego numeru REGON zwraca kilka podmiotów albo gdy podany typDzialalnosci nie pasuje do żadnego z nich. Komunikat podaje dostępne typy, na przykład [CEIDG, OTHER]. Ponów żądanie z właściwą wartością pola typDzialalnosci.

Błąd treści HTML lub JS

Komunikat „Przekazane dane zawierają niedozwoloną treść HTML/JS” oznacza, że w polu tekstowym są znaczniki, encje albo znaki < i >. Oczyść tekst przed wysłaniem – szczególnie gdy przedmiot umowy kopiujesz z systemu, który przechowuje go jako HTML.

Błąd certyfikatu TLS

Komunikaty typu „PKIX path building failed”, „unable to find valid certification path” czy „ORA-29024: Certificate validation failure” zwykle wynikają z konfiguracji po stronie klienta:

• nieaktualny truststore albo Oracle Wallet,
• serwer proxy z inspekcją SSL, który podmienia certyfikat,
• brak zaufania do urzędu certyfikacji używanego w organizacji.

Zaktualizuj magazyn certyfikatów albo dodaj wyjątek w proxy dla domen CRU.

Nie można zaktualizować ani wycofać umowy

Przez API można zmieniać i wycofywać tylko umowy opublikowane, dla których nie rozpoczęto zmian w aplikacji. Jeśli ktoś edytuje umowę ręcznie, najpierw trzeba zakończyć lub odrzucić tę zmianę. Wycofanie nieistniejącej umowy zwraca status NOT_EXISTS.

Gdzie zgłosić błąd API?

• pracownicy jednostek publicznych i integratorzy działający w ich strukturach: [email protected],
• integratorzy zewnętrzni (firmy dostarczające oprogramowanie): [email protected].

Opisz środowisko, datę i godzinę, wysłane żądanie (bez klucza API), otrzymaną odpowiedź i oczekiwany wynik.

Stan na 11 października 2026 r. Artykuł ma charakter informacyjny i nie stanowi porady prawnej.

Źródło: opracowano na podstawie materiałów Ministerstwa Finansów o Centralnym Rejestrze Umów JSFP (gov.pl/web/finanse, w tym najczęściej zadawanych pytań, podręcznika użytkownika i dokumentacji API) udostępnianych na licencji CC BY-SA 4.0. Treść została opracowana od nowa własnymi słowami i uzupełniona; artykuł udostępniamy na tej samej licencji.