Błędy

Każda odpowiedź o błędzie z /api/v1/* zawiera stabilne, czytelne dla maszyn pole code. Partnerzy filtrują według pola code, a nie statusu HTTP (statusy są współdzielone przez wiele kodów) ani pola message (które jest lokalizowane). Przestrzeń kodów działa wyłącznie w trybie dopisywania: raz wdrożony kod nigdy nie zostanie zmieniony, przenumerowany ani usunięty.

Struktura odpowiedzi

Typowa odpowiedź 400:

{
  "code": "VALIDATION_FAILED",
  "message": "Name is required.",
  "errors": { "name": ["Name is required."] }
}

code: jedna z wartości w poniższym katalogu. Należy filtrować na jej podstawie.
message: czytelny dla człowieka opis, zlokalizowany zgodnie z nagłówkiem Accept-Language klienta (domyślnie hr). Nie należy przetwarzać tej wartości programistycznie.
errors: występuje w odpowiedziach VALIDATION_FAILED. Słownik, w którym kluczami są nazwy pól, a wartościami tablice zlokalizowanych komunikatów dla każdego pola.

Błędy serwera (HTTP 500) pomijają słownik errors i zawierają ogólny komunikat. Należy ponowić próbę z opóźnieniem (back-off). Jeśli błąd będzie się powtarzał, należy skontaktować się ze wsparciem technicznym, podając identyfikator żądania (widoczny w nagłówku odpowiedzi X-Request-Id, jeśli jest obecny).

Katalog

Kod	HTTP	Kiedy występuje	Reakcja partnera
`VALIDATION_FAILED`	400	Walidacja treści żądania nie powiodła się lub brakuje wymaganego nagłówka.	Sprawdź słownik `errors`. Wyświetl użytkownikowi końcowemu komunikaty na poziomie poszczególnych pól.
`EXCHANGE_RATE_UNAVAILABLE`	400	Dostawca kursów walut organizacji nie publikuje kursu dla danej waluty w żądanym dniu i nie istnieje żaden kurs historyczny, którego można by użyć jako awaryjnego.	Błąd z rodziny walidacji z obiektem `errors` mapowanym na pola. Poproś użytkownika o ręczne wprowadzenie kursu lub wybierz walutę obsługiwaną przez dostawcę.
`UNAUTHORIZED`	401	Brak klucza API, jest on nieprawidłowo sformatowany lub został unieważniony.	Sprawdź nagłówek `Authorization`. Wygeneruj klucz ponownie, jeśli został unieważniony.
`API_ACCESS_NOT_ENABLED`	402	Docelowa firma nie posiada funkcji subskrypcji `ApiAccess`.	Zmień plan firmy na Enterprise lub dodaj dodatek `ApiAccess` w ustawieniach rozliczeń.
`FORBIDDEN`	403	Uwierzytelniono pomyślnie, ale użytkownik, który wygenerował klucz, nie ma uprawnień do wykonania tej operacji w tym zakresie.	Sprawdź rolę aktywnego użytkownika w docelowej firmie. Wygeneruj klucz ponownie jako administrator.
`NOT_FOUND`	404	Docelowy zasób nie istnieje lub został usunięty.	Zweryfikuj identyfikator. Zasób mógł zostać usunięty przez innego użytkownika.
`CONFLICT`	409	Zduplikowany zasób, nieaktualny warunek wstępny lub ponowne przesłanie klucza idempotencji z inną treścią żądania.	Uzgodnij stan danych. Ponowna próba może się powieść z innym payloadem lub może nie wymagać żadnego działania.
`RATE_LIMIT_EXCEEDED`	429	Przekroczono limit zapytań dla klucza (sekundowy, godzinowy lub dzienny).	Wstrzymaj wysyłanie żądań zgodnie z nagłówkiem `Retry-After`. Zobacz Limity zapytań.
`KEY_REVOKED`	401	Zarezerowane dla przyszłej niestandardowej obsługi wyzwań (challenge handler). Obecnie nie jest zwracane.	Przygotuj wcześniej swój kod obsługi. Obecnie proces unieważnionego klucza zwraca czysty kod HTTP 401.
`INTERNAL_ERROR`	500	Nieobsługiwany błąd serwera.	Ponów próbę z wykładniczym opóźnieniem (exponential back-off). Jeśli błąd będzie się powtarzał, skontaktuj się ze wsparciem technicznym.

Gwarancja wyłącznie dopisywania

Raz wdrożony kod pozostaje w katalogu na zawsze, nawet jeśli generujący go element zostanie usunięty. Partnerzy mogą mieć pewność, że ich instrukcje warunkowe switch oparte na polu code nigdy nagle nie przestaną działać z powodu zmiany nazwy wartości przez locco. Jeśli zachowanie powiązane z danym kodem ulegnie zmianie (inny status HTTP, nowe ograniczenie), zostanie to opisane w dzienniku zmian (changelog); sam ciąg znaków kodu pozostaje stabilny.

Zachęca się partnerów do defensywnej obsługi nieznanych kodów: jeśli nowy kod zostanie wdrożony przed aktualizacją Twojego klienta, należy potraktować go jako ogólny błąd (prawdopodobnie o strukturze zbliżonej do INTERNAL_ERROR) i zapisać surową odpowiedź w logach do późniejszej analizy, zamiast doprowadzać do awarii aplikacji.