# 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](https://vercom.gitbook.io/emaillabs-api-docs).

## **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:

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

{% hint style="warning" %}
**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.
{% endhint %}

## 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.

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

***

### **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.

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

## **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.