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 kodu statusu HTTP w zakresie 4xx lub 5xx. W takich przypadkach ciało odpowiedzi zazwyczaj zawiera szczegółowe informacje o błędzie.

Integracja musi powiadamiać dewelopera integracji o występujących błędach, aby można było zidentyfikować i rozwiązać ich przyczyny. Jeśli błędy występują stale, 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 występują wewnętrzne błędy serwera po stronie API.

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.

Jeśli jednak żądanie stale zwraca błąd 500, integracja musi zaprzestać jego wysyłania i zgłosić problem.

Deweloper integracji powinien skontaktować się z pomocą techniczną Syrve, przekazując szczegółowy opis 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.

Deweloper integracji odpowiada 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 każdej 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ę jednokrotnego 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 mają ograniczony czas ważności 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 wspomnianej jednokrotnej próby po wygaśnięciu tokena.

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

Jeśli problem nie zostanie rozwiązany, adres IP zostanie ostatecznie zablokowany — może to wpłynąć na wszystkie integracje hostowane na tym samym serwerze, a 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 pod względem struktury, 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ć wysyłania takich żądań i zgłosić problem.

Deweloper integracji odpowiada za rozwiązanie problemu.

Nierozwiązane błędy 403 spowodują zablokowanie loginu API.

404 Not Found

Błąd 404 jest zwracany, gdy żądana 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ć wysyłania żądań 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 — potencjalnie wpływając 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ć wysyłania żądań 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ć dewelopera. Problem może nie być związany z obciążeniem, lecz z charakterem przesyłanych danych.

Deweloper integracji powinien skontaktować się z pomocą techniczną Syrve, przekazując szczegóły.

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ć wysyłania żądań i zgłosić problem.

Deweloper integracji powinien zidentyfikować i naprawić 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ń za bardzo długi okres lub dla dużej liczby 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. Deweloper integracji musi zidentyfikować i naprawić 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 jest resetowany i integracja może wykonać kolejne 10 żądań.

Jeśli żądanie stale skutkuje błędem 429, integracja musi zaprzestać jego wykonywania i zgłosić problem. Deweloper integracji powinien zmniejszyć częstotliwość wykonywania 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.