Obsługa błędów

Integracja musi obsługiwać wszelkie błędy otrzymywane podczas wywoływania metod Live API. Błąd definiuje się jako otrzymanie statusu odpowiedzi HTTP z zakresu 4xx lub 5xx. W takich przypadkach ciało odpowiedzi zazwyczaj zawiera szczegółowe informacje o błędzie.

Integracja musi powiadomić programistę integracji o wszelkich występujących błędach, aby można było zidentyfikować i rozwiązać ich przyczyny. Jeśli błędy występują konsekwentnie, oznacza to problem wymagający rozwiązania. Jeśli integracja zignoruje błędy i będzie kontynuować wysyłanie żądań, które je wywołują, zostanie zablokowana — co oznacza, że Live API przestanie przetwarzać jakiekolwiek żądania z powiązanego loginu API.

Jeśli integracja będzie kontynuować wysyłanie żądań nawet po zablokowaniu loginu API i nadal ignorować błędy, wszystkie żądania z tego adresu IP zostaną zablokowane. Może to prowadzić do całkowitej blokady nie tylko wadliwej integracji, ale także innych integracji działających na tym samym środowisku hostingowym.

Poniżej znajdują się standardowe kody błędów, ich typowe przyczyny oraz wytyczne dotyczące ich obsługi:

500 Internal Server Error

Live API zwraca kod statusu 500, gdy po stronie API występują wewnętrzne błędy serwera.

Integracja może ponowić żądanie po krótkim opóźnieniu. Jeśli problem był tymczasowy i został rozwiązany, żądanie może zakończyć się sukcesem.

Jednak jeśli żądanie konsekwentnie zwraca błąd 500, integracja musi zaprzestać jego wysyłania i zgłosić problem.

Programista integracji powinien skontaktować się z pomocą techniczną Syrve z dokładnym opisem problemu.

400 Bad Request

Błąd 400 jest zwracany, gdy żądanie jest niepoprawnie sformułowane — na przykład brakuje wymaganych pól w ciele żądania.

Zazwyczaj wskazuje to na nieprawidłową implementację integracji. Konkretna wiadomość o błędzie jest zwykle zawarta w odpowiedzi, na przykład:

Error converting value {null} to type 'System.Guid'. Path 'productId', line 66, position 25.

Takich żądań nie należy ponawiać, ponieważ zawsze zakończą się tym samym błędem.

W przypadku powtarzających się błędów 400 integracja musi zaprzestać wysyłania tych żądań i zgłosić problem.

Programista integracji jest odpowiedzialny za zidentyfikowanie i naprawę przyczyny.

Jeśli problem nie zostanie rozwiązany, integracja zostanie zablokowana, a Live API przestanie przetwarzać żądania z tego loginu API.

401 Unauthorized, 402 Payment Required, 423 Locked

Dla dowolnej metody Live API poza /api/1/access_token może zostać zwrócony błąd 401 w następujących przypadkach:

Token w nagłówku Authorization wygasł.
Login API został zablokowany.

W przypadku błędu 401 integracja musi podjąć próbę jednorazowego ponownego wywołania metody /api/1/access_token, aby uzyskać nowy token. Jeśli się powiedzie, wygasły token powinien zostać zastąpiony nowym w kolejnych żądaniach.

Jest to oczekiwane zachowanie — tokeny dostępu są ograniczone czasowo i muszą być regularnie odnawiane.

Jednak wywoływanie /api/1/access_token przed każdym wywołaniem API jest niepotrzebne i nieefektywne.

Jeśli sama metoda /api/1/access_token zwróci błąd 401, login API jest zablokowany. Możliwe przyczyny to:

Licencja Live API wygasła. Odpowiedź będzie zawierać komunikat:

"Apilogin's license for using the Live API has expired."

Skontaktuj się z pomocą techniczną Syrve w celu odnowienia licencji.
Integracja wielokrotnie ignorowała inne typy błędów (np. 400, 429) bez rozwiązania podstawowych problemów.

Odpowiedź będzie zawierać komunikat:

"Apilogin has been blocked."

Skontaktuj się z pomocą techniczną Syrve po pomoc.

Inne przyczyny błędu 401 przy wywołaniu /api/1/access_token to:

Nieprawidłowy lub brakujący apiLogin:
- "Login ... is not authorized." Pole apiLogin zawiera login, który nie istnieje.
- "ApiLogin is absent." Pole apiLogin jest nieobecne.
- "Value cannot be null. (Parameter 'apiLogin')". Pole apiLogin jest puste.

Te błędy nie powinny być ponawiane, z wyjątkiem jednorazowej próby po wygaśnięciu tokena, o której mowa powyżej.

W przypadku powtarzających się błędów 401 integracja musi zaprzestać wysyłania problematycznych żądań i powiadomić programistę. Programista integracji powinien wyjaśnić problem i usunąć przyczynę.

Jeśli problem nie zostanie rozwiązany, adres IP ostatecznie zostanie zablokowany — może to wpłynąć na wszystkie integracje hostowane na tym samym serwerze, nie tylko na wadliwą.

W niektórych przypadkach błąd 401 może zostać zastąpiony błędem 402 lub 423. Należy je obsługiwać w taki sam sposób, jak opisano powyżej.

403 Forbidden

Błąd 403 jest zwracany, gdy żądanie jest poprawne strukturalnie, ale narusza zasady dostępu — na przykład żądanie zawiera identyfikator organizacji niepowiązany z loginem API. Odpowiedź na żądanie zazwyczaj zawiera dokładną przyczynę błędu.

Takich żądań nie należy ponawiać.

W przypadku powtarzających się błędów 403 integracja musi zaprzestać takich żądań i zgłosić problem.

Programista integracji jest odpowiedzialny za rozwiązanie problemu.

Nierozwiązane błędy 403 skutkują zablokowaniem loginu API.

404 Not Found

Błąd 404 jest zwracany, gdy wywoływana jest nieistniejąca metoda Live API — zazwyczaj z powodu niepoprawnego URL.

Nie należy ponawiać takich żądań.

W przypadku powtarzających się błędów 404 integracja musi zaprzestać i zgłosić problem.

Jeśli problem nie zostanie rozwiązany, login API zostanie zablokowany.

W niektórych przypadkach, jeśli wywołująca integracja nie może zostać zidentyfikowana na podstawie wywoływanej metody, wszystkie żądania z powiązanego adresu IP mogą zostać zablokowane — co może wpłynąć na inne integracje na tym samym hoście.

405 Method Not Allowed

Błąd 405 występuje, gdy użyta jest nieprawidłowa metoda HTTP — na przykład wywołanie metody POST jako GET.

Nie należy ponawiać takich żądań.

W przypadku powtarzających się błędów 405 integracja musi zaprzestać i zgłosić problem.

Jeśli problem nie zostanie rozwiązany, login API zostanie zablokowany.

408 Request Timeout

Błąd 408 jest zwracany, gdy Live API jest pod dużym obciążeniem.

Integracja może ponowić żądanie po opóźnieniu. Jeśli problem będzie się utrzymywał, integracja powinna zaprzestać wysyłania żądania i powiadomić programistę. Problem może nie być związany z obciążeniem, lecz z charakterem przesyłanych danych.

Programista integracji powinien skontaktować się z pomocą techniczną Syrve z szczegółami.

410 Gone

Błąd 410 jest zwracany specyficznie dla metody /api/1/commands/status, gdy podany jest nieprawidłowy lub wygasły CorrelationId.

Identyfikatory korelacji są ważne tylko przez 30 minut od momentu wydania oryginalnego polecenia.

Nie należy ponawiać takich żądań.

W przypadku powtarzających się błędów 410 należy zaprzestać i zgłosić problem.

Programista integracji powinien zidentyfikować i usunąć przyczynę.

Jeśli problem nie zostanie rozwiązany, login API zostanie zablokowany.

422 Unprocessable Content

Live API zwraca błąd 422, jeśli żądanie mogłoby skutkować pobraniem nadmiernie dużej ilości danych (na przykład zamówień dla bardzo dużego zakresu dat lub dla wielu organizacji). Dokładna przyczyna błędu jest zwykle zawarta w odpowiedzi API.

Integracja musi zostać dostosowana tak, aby pojedyncze problematyczne żądanie zostało podzielone na kilka żądań, z których każde zwraca mniejszą ilość danych.

Integracja nie powinna próbować ponawiać takiego żądania, ponieważ kolejne wywołania zakończą się tym samym błędem. W przypadku wielu błędów 422 integracja musi zaprzestać wykonywania problematycznych żądań i zgłosić problem. Programista integracji musi zidentyfikować i usunąć przyczynę problemu.

Jeśli problem nie zostanie rozwiązany, integracja zostanie zablokowana, co oznacza, że Live API przestanie przetwarzać żądania z danego loginu API.

429 Too Many Requests

Live API zwraca błąd 429, gdy metoda jest wywoływana zbyt często. Każda metoda ma własny limit częstotliwości, a po jego przekroczeniu dalsze wywołania tej metody skutkują błędem 429.

Na przykład, jeśli limit wynosi 10 żądań na godzinę, pierwsze 10 żądań zostanie przetworzonych pomyślnie, a wszystkie kolejne zakończą się błędem 429. Po upływie godziny licznik zostaje zresetowany i integracja może wykonać kolejne 10 żądań.

Jeśli żądanie konsekwentnie skutkuje błędem 429, integracja musi zaprzestać jego wykonywania i zgłosić problem. Programista integracji powinien zmniejszyć częstotliwość wywoływania problematycznego żądania. Zalecane limity częstotliwości żądań można uzyskać od pomocy technicznej Syrve.

Jeśli integracja wielokrotnie otrzymuje błędy 429, a liczba nieudanych żądań jest porównywalna z liczbą udanych, integracja zostanie zablokowana, co oznacza, że Live API przestanie przetwarzać żądania z danego loginu API.