Kody Błędów

Zrozumienie odpowiedzi błędów API i sposobów ich obsługi.

Przegląd

API zwraca ustandaryzowane odpowiedzi błędów z konkretnymi kodami błędów, aby pomóc w identyfikacji i rozwiązywaniu problemów.

Format Odpowiedzi Błędu

Wszystkie odpowiedzi błędów mają następującą strukturę:

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Brakujące dane uwierzytelniające",
    "details": "Pola 'username' i 'password' są wymagane",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Błędy Uwierzytelniania (1000-1099)

Błędy związane z danymi logowania i uwierzytelnianiem.

KodHTTPWiadomośćRozwiązanie
AUTH_1001 401 Brakujące dane uwierzytelniające Dołącz nazwę użytkownika i hasło w żądaniu
AUTH_1002 401 Nieprawidłowa nazwa użytkownika lub hasło Sprawdź, czy dane uwierzytelniające są poprawne
AUTH_1003 403 Konto tymczasowo zablokowane Poczekaj przed ponowną próbą lub skontaktuj się z pomocą

Błędy Limitu (1100-1199)

Błędy związane z limitem API i limitami użycia.

KodHTTPWiadomośćRozwiązanie
QUOTA_1101 403 Niewystarczający limit API Kup więcej kredytów lub sprawdź limit
QUOTA_1102 429 Limit API przekroczony Poczekaj na odnowienie limitu lub ulepsz plan

Błędy Walidacji (2000-2099)

Błędy związane z walidacją żądania i danymi wejściowymi.

KodHTTPWiadomośćRozwiązanie
VAL_2001 400 Nie przesłano pliku Dołącz plik w żądaniu
VAL_2002 400 Nieprawidłowy format pliku Użyj obsługiwanych formatów: PDF, PNG, JPG, WEBP
VAL_2003 400 Wiele plików PDF niedozwolone Prześlij jeden PDF lub wiele obrazów
VAL_2004 400 PDF i obrazy nie mogą być mieszane Prześlij PDF lub obrazy, nie oba jednocześnie
VAL_2005 400 Nieobsługiwany kod języka Użyj obsługiwanego kodu języka

Błędy Przetwarzania (3000-3099)

Błędy podczas przetwarzania dokumentu i analizy AI.

KodHTTPWiadomośćRozwiązanie
PROC_3001 500 Niepowodzenie przetwarzania dokumentu Sprawdź jakość obrazu, spróbuj ponownie
PROC_3002 500 Niepowodzenie ekstrakcji metadanych Upewnij się, że dokument zawiera czytelny tekst
PROC_3003 500 Niepowodzenie ekstrakcji parametrów Sprawdź, czy format badania krwi jest rozpoznawalny
PROC_3006 504 Przekroczono limit czasu przetwarzania Zmniejsz rozmiar pliku lub podziel na wiele żądań

Błędy Serwera (5000-5099)

Wewnętrzne błędy serwera i problemy z dostępnością usługi.

KodHTTPWiadomośćRozwiązanie
SRV_5001 500 Wewnętrzny błąd serwera Spróbuj ponownie, skontaktuj się z pomocą, jeśli problem się powtarza
SRV_5002 503 Usługa tymczasowo niedostępna Poczekaj i spróbuj ponownie z wykładniczym opóźnieniem

Najlepsze Praktyki Obsługi Błędów

Zalecenia
  1. Zawsze sprawdzaj pole status - Odpowiedzi sukcesu mają "status": "success"
  2. Zaimplementuj logikę ponawiania dla błędów przejściowych (5xx) z wykładniczym opóźnieniem
  3. Rejestruj kody błędów do debugowania i monitorowania
  4. Wyświetlaj przyjazne komunikaty na podstawie kodów błędów
  5. Używaj punktów końcowych sandbox do testowania obsługi błędów