not_found kontra unavailable — różnica, która decyduje o poprawności integracji

Dwa różne zdarzenia, jedna odpowiedź

Twój system pyta rejestr o firmę i nie dostaje danych. Mogło się wydarzyć jedno z dwojga:

• Rejestr odpowiedział, że takiego wpisu nie ma — to jest informacja. Wiesz coś nowego o świecie.
• Rejestr nie odpowiedział — timeout, błąd 500, blokada limitu, przerwa techniczna. To jest brak informacji. Nie wiesz nic.

Większość integracji domowej roboty skleja te przypadki w jedno: pusta odpowiedź, null, pusta tablica. I tu zaczyna się kłopot, bo „nie ma wpisu” i „nie wiem” to nie to samo, a konsekwencje bywają odwrotne.

Gdzie to boli naprawdę

Weźmy screening sankcyjny. Pytasz o kontrahenta, lista sankcyjna akurat jest niedostępna, a Twój system pokazuje „brak trafień”. Formalnie sprawdziłeś. Faktycznie — nie sprawdziłeś nic, ale masz w dokumentacji zapis, że sprawdzenie się odbyło i wypadło czysto.

Najgorszy wynik to nie błąd, który widać. Najgorszy to fałszywe „czysto”, które trafia do dokumentacji i wygląda jak dowód należytej staranności.

To samo dotyczy wpisów o niewypłacalności, beneficjentów rzeczywistych i statusu VAT. Za każdym razem, gdy niedostępność źródła zostanie przedstawiona jako brak wpisu, powstaje dokument, który mówi więcej, niż wiadomo.

Jak to modelować

Odpowiedź z rejestru powinna nieść stan danych, a nie tylko kod HTTP transportu. U nas są to trzy rozłączne przypadki:

• found — rejestr odpowiedział i ma wpis,
• not_found — rejestr odpowiedział i wpisu nie ma,
• unavailable — rejestr nie odpowiedział; danych po prostu nie ma skąd wziąć.

Kod HTTP opisuje przy tym nasze API, nie rejestr. „Nie ma takiej firmy” to poprawne 200 ze statusem not_found w treści — a nie 404, bo zapytanie zostało obsłużone prawidłowo.

Konsekwencja, która porządkuje resztę

Skoro unavailable nie jest informacją, to nie powinno być też pozycją na fakturze. U nas found i not_found kosztują tyle samo — obie są odpowiedzią rejestru — a unavailable nie kosztuje nic. Klient nie płaci za to, że komuś innemu padł serwer.

Ta sama zasada powinna obowiązywać w Twojej integracji, nawet jeśli nikomu nie wystawiasz faktury: jeśli nie wiesz, zapisz, że nie wiesz. Ponów później. Nie zamieniaj ciszy w odpowiedź.

Co z tym zrobić po swojej stronie

• Rozdziel w modelu danych „brak wpisu” od „brak odpowiedzi” — dwa różne pola albo enum, nigdy jeden boolean.
• W interfejsie pokazuj niedostępność wprost, zamiast domyślnie zielonego „czysto”.
• Ponawiaj unavailable, nie ponawiaj not_found — to już jest odpowiedź.
• W dokumentacji audytowej zapisuj, które źródło było niedostępne i kiedy.

Jak wygląda koperta odpowiedzi z jawnym statusem i datą ważności danych: dokumentacja Rejestry API.

Materiał ma charakter informacyjny i edukacyjny. Opisane rozróżnienie dotyczy projektowania integracji z rejestrami publicznymi i nie stanowi porady prawnej ani compliance.