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:

json
{
  "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.