Błędy Interfejsu API – Najczęstsze Kody Błędów

Podczas korzystania z interfejsu API EmailLabs mogą wystąpić błędy związane z nieprawidłowym żądaniem, problemami z autoryzacją lub wewnętrznymi problemami systemowymi. Zrozumienie kodów odpowiedzi API pozwala szybciej reagować na problemy i zwiększyć niezawodność integracji.

Nasze API wykorzystuje standardowe kody statusu HTTP oraz komunikaty w formacie JSON opisujące źródło problemu. Pełna specyfikacja dostępna jest w naszej głównej dokumentacji API.

Struktura Odpowiedzi Błędu

W przypadku wystąpienia błędu, API zazwyczaj zwraca odpowiedź w formacie JSON, która zawiera więcej szczegółów niż sam kod statusu HTTP.

Przykładowa struktura odpowiedzi błędu:

{
  "error": {
    "code": 422,
    "message": "Invalid input data.",
    "details": {
      "to": [
        "The 'to' field must be a valid email address."
      ]
    }
  }
}

Ważna uwaga: Poniższe tabele przedstawiają typowe zastosowanie kodów statusu HTTP w kontekście naszego API. Należy jednak pamiętać, że ostatecznym i najdokładniejszym źródłem informacji o przyczynie błędu jest zawsze pełna treść odpowiedzi API w formacie JSON (szczególnie pola message i details), a nie tylko sam numer kodu statusu.

Klasyfikacja Kodów Błędów

Najczęściej spotykane kody odpowiedzi dzielimy na kilka kategorii:

• 2XX – Sukces: Żądanie zostało poprawnie przetworzone.

• 4XX – Błąd klienta: Błąd w żądaniu – wymagane poprawki po stronie aplikacji wysyłającej żądanie.

• 5XX – Błąd serwera: Wewnętrzny błąd usługi – zalecany kontakt z pomocą techniczną lub ponowna, ostrożna próba.

Błędy Klienta (4XX)

Kody z tego zakresu sygnalizują problemy leżące po stronie klienta. Wskazują, że żądanie było niepoprawne lub nie mogło zostać zrealizowane.

Kod	Znaczenie	Opis
400	Nieprawidłowe żądanie	Brakuje wymaganych pól lub dane mają nieprawidłowy format (np. niepoprawna struktura JSON).
401	Brak autoryzacji	Nieprawidłowy lub brakujący token API. Należy upewnić się, że nagłówek Authorization jest ustawiony poprawnie.
403	Dostęp zabroniony	Użytkownik nie ma uprawnień do wykonania danej operacji (np. próba wysyłki z niezweryfikowanej domeny).
404	Nie znaleziono zasobu	Próba odwołania do nieistniejącego zasobu (np. zapytanie o status wiadomości z nieprawidłowym message_id).
422	Nieprawidłowe dane wejściowe	Walidacja danych zakończona niepowodzeniem – np. błędny format adresu e-mail, brak tematu wiadomości.
429	Zbyt wiele żądań	Przekroczony limit zapytań do API w danym oknie czasowym (tzw. rate limiting).

---

Błędy Serwera (5XX)

Kody z tego zakresu informują o problemach po stronie serwera API, które uniemożliwiły obsłużenie prawidłowo sformułowanego żądania.

Kod	Znaczenie	Opis
500	Wewnętrzny błąd serwera	Wystąpił nieoczekiwany błąd po naszej stronie. Zalecany kontakt z pomocą techniczną, jeśli problem się powtarza.
502	Błędna odpowiedź bramy	Serwis pomocniczy (np. system kolejkowania) zwrócił nieprawidłową odpowiedź. Problem jest zazwyczaj chwilowy.
503	Usługa niedostępna	API jest chwilowo przeciążone lub w trakcie prac konserwacyjnych. Należy spróbować ponownie po chwili.
504	Przekroczono limit czasu	Czas oczekiwania serwera na odpowiedź minął. Może to być spowodowane chwilowym, dużym obciążeniem systemu.

Dobre Praktyki Obsługi Błędów API

• Loguj wszystkie odpowiedzi: Zawsze loguj pełną treść odpowiedzi API (zarówno sukcesy, jak i błędy), aby ułatwić debugowanie.

• Implementuj mechanizmy ponowień: W przypadku błędów z serii 5XX, zaimplementuj w swojej aplikacji mechanizm ponawiania żądania z rosnącym opóźnieniem (tzw. exponential backoff).

• Obsługuj błędy walidacji: Parsuj pole details w odpowiedziach z kodem 422, aby programowo obsługiwać błędy walidacji lub prezentować je użytkownikowi.

• Monitoruj błędy: Regularnie analizuj logi w poszukiwaniu powtarzających się błędów, które mogą wskazywać na problem w Twojej integracji.