Obsługa błędów
API wykorzystuje konwencjonalne kody odpowiedzi HTTP do wskazania sukcesu lub niepowodzenia żądań. Ta strona dokumentuje formaty błędów i strategie ich obsługi.
Format odpowiedzi o błędzie
Wszystkie odpowiedzi o błędzie mają spójną strukturę JSON:
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Pole | Opis |
|---|---|
| error | Maszynowo czytelny kod błędu |
| message | Czytelny dla człowieka opis błędu |
| timestamp | Kiedy wystąpił błąd |
| path | Ścieżka żądanego punktu końcowego |
| details | Dodatkowe szczegóły błędów walidacji (opcjonalnie) |
Kody statusu HTTP
| Kod | Opis |
|---|---|
| 400 | Nieprawidłowe parametry żądania lub błędnie skonstruowane ciało żądania |
| 401 | Brakujący lub nieprawidłowy klucz API |
| 403 | Klucz API nie ma wymaganych uprawnień dla tego punktu końcowego |
| 404 | Żądany zasób nie istnieje |
| 429 | Przekroczono limit żądań - spróbuj ponownie po określonym czasie |
| 500 | Wewnętrzny błąd serwera - skontaktuj się z pomocą techniczną, jeśli problem będzie się utrzymywał |
| 503 | Usługa tymczasowo niedostępna - spróbuj ponownie później |
Strategia ponawiania prób
W przypadku błędów przejściowych wdróż strategię ponawiania prób z wykładniczym opóźnieniem:
- W przypadku błędów 429, przed ponowną próbą poczekaj czas określony w nagłówku X-RateLimit-Reset
- W przypadku błędów 5xx, użyj wykładniczego opóźnienia (1s, 2s, 4s, 8s...) z jitterem
- Ustaw maksymalną liczbę ponawianych prób (np. 3-5 prób), aby uniknąć pętli nieskończonych
Ograniczanie częstotliwości żądań
Po przekroczeniu limitu żądań API zwraca kod statusu 429 ze szczegółami dotyczącymi momentu, w którym można ponowić próbę:
Użyj pola retryAfter lub nagłówka X-RateLimit-Reset, aby określić, kiedy ponowić próbę wysłania żądania.
Błędy walidacji
W przypadku błędów 400 odpowiedź zawiera tablicę szczegółów (details) z błędami na poziomie poszczególnych pól:
Najlepsze praktyki obsługi błędów
- Zawsze sprawdzaj kod statusu HTTP przed parsowaniem treści odpowiedzi
- Implementuj wykładnicze wycofywanie (exponential backoff) dla błędów 429 i 5xx
- Loguj błędy wraz ze znacznikiem czasu i ścieżką na potrzeby debugowania
- Obsłuż konkretne kody błędów inaczej (np. 401 wyzwala ponowne uwierzytelnienie)