Błędy API

API informuje o błędach standardowymi kodami stanu HTTP i jednolitą treścią odpowiedzi. Pomyślne odpowiedzi zwracają dane bezpośrednio, bez opakowania w kopertę.

Format błędu

W przypadku błędu treść odpowiedzi to obiekt JSON z jednym polem error, zawierającym komunikat czytelny dla człowieka:

{"error":"reaction not found"}

Kieruj się przede wszystkim kodem stanu HTTP, a tekst error wykorzystuj do logowania i komunikatów dla użytkownika.

Kody stanu

  • 200 OK — żądanie zakończone sukcesem, dane w treści.
  • 201 Created — utworzono nowy zasób (część endpointów POST).
  • 204 No Content — sukces bez treści (część operacji usunięcia).
  • 400 Bad Request — nieprawidłowe ciało lub parametry żądania.
  • 401 Unauthorized — token brakuje, jest nieprawidłowy lub wygasł; albo ścieżka jest niedostępna przez token personalny.
  • 402 Payment Required — akcja przekracza limit planu lub kwoty (np. własna biblioteka mediów wymaga planu premium).
  • 403 Forbidden — token nie posiada wymaganego zakresu dostępu dla tej ścieżki.
  • 404 Not Found — zasób nie istnieje lub nie należy do Ciebie.
  • 409 Conflict — konflikt stanu (np. duplikat unikalnej wartości).
  • 422 Unprocessable Entity — treść jest syntaktycznie poprawna, ale nie przechodzi walidacji domeny.
  • 429 Too Many Requests — przekroczono limit zapytań (zob. limity).
  • 500 Internal Server Error — wewnętrzny błąd serwera; spróbuj ponownie później.

Jak obsługiwać błędy

Za sukces uznawaj kody 2xx. Przy 401/403 sprawdź token i jego zakresy dostępu. Przy 4xx (z wyjątkiem 429) nie powtarzaj żądania bez zmian — popraw je. Przy 429 i 5xx stosuj ponowienie z wykładniczym opóźnieniem.

Co dalej