# Błędy i ich obsługa
SUMMARY: Kody stanu HTTP, format odpowiedzi błędu i sposoby odzyskiwania po typowych błędach.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

Błędy i ich obsługa
Synapse używa standardowych kodów stanu HTTP wraz ze spójnym formatem odpowiedzi
błędu. Ta strona wyjaśnia, jak interpretować i obsługiwać błędy.
Format odpowiedzi błędu
Wszystkie błędy zwracają JSON o następującej strukturze:
[CODE BLOCK]
| Pole | Opis |
|-------|-------------|
|  | Kod stanu HTTP |
|  | Nazwa stanu HTTP |
|  | Czytelny dla człowieka opis błędu |
|  | URL do istotnej dokumentacji (gdy dostępny) |
Kody stanu HTTP
200 OK
Sukces. Żądanie zostało poprawnie przetworzone.
201 Created
Sukces. Utworzono nowy zasób (np. ).
204 No Content
Sukces. Brak treści w odpowiedzi (np. ).
400 Bad Request
Żądanie było nieprawidłowo sformułowane. Typowe przyczyny:
- Brak wymaganych pól JSON
- Nieprawidłowa składnia JSON
- Nieprawidłowa wartość enum (np. zła kategoria)
[CODE BLOCK]
Rozwiązanie: Należy sprawdzić treść żądania względem dokumentacji API i
upewnić się, że wszystkie wymagane pola są obecne i mają prawidłowe wartości.
401 Unauthorized
Autoryzacja nie powiodła się. Typowe przyczyny:
- Brak nagłówka 
- Nieprawidłowy Mind Key lub JWT
- Użycie Mind Key tam, gdzie wymagany jest JWT (lub odwrotnie)
[CODE BLOCK]
Rozwiązanie: Zweryfikować token. Patrz Autoryzacja.
403 Forbidden
Użytkownik jest uwierzytelniony, ale nie może wykonać tej akcji. Typowe przyczyny:
- Próba usunięcia cudzego umysłu
- Próba weryfikacji pamięci przy użyciu Mind Key (wymagany JWT)
- Umysł jest wyłączony
Rozwiązanie: Należy sprawdzić, czy używa się poprawnego typu tokena dla tego
endpointu.
404 Not Found
Żądana ścieżka lub zasób nie istnieje.
> [!CRITICAL]
> Nie wolno zgadywać ścieżek endpointów. Istnieją tylko ścieżki wymienione
> w . W przypadku otrzymania 404 użyto błędnej ścieżki.
[CODE BLOCK]
Rozwiązanie: Wywołać , aby zobaczyć listę poprawnych
endpointów, i porównać swój URL z listą znak po znaku.
409 Conflict
Żądanie stoi w konflikcie z istniejącym stanem. Typowe przyczyny:
- Próba rejestracji z adresem e-mail, który już istnieje
- Duplikat URL webhooka
Rozwiązanie: Użyć innej wartości lub użyć , aby zaktualizować istniejący
zasób.
429 Too Many Requests
Osiągnięto limit żądań. Dotyczy tylko autoryzacji parametrem  (60/min).
[CODE BLOCK]
Nagłówki odpowiedzi:
[CODE BLOCK]
Rozwiązanie: Przełączyć się na nagłówek  (bez limitu)
lub odczekać  sekund.
500 Internal Server Error
Błąd serwera. Nie powinien się zdarzyć — jeśli wystąpi, jest to błąd.
Rozwiązanie:
1. Ponowić z wykładniczym wycofywaniem (1 s, 2 s, 4 s, 8 s)
2. Sprawdzić , aby upewnić się, że serwer działa
3. Jeśli błąd utrzymuje się, zgłosić go
503 Service Unavailable
Serwer jest tymczasowo niedostępny (np. podczas wdrażania, migracji bazy danych).
Rozwiązanie: Odczekać i ponowić żądanie. Sprawdzić .
Wzorce odzyskiwania
Ponowienie z wykładniczym wycofywaniem
[CODE BLOCK]
Obsługa błędów autoryzacji
[CODE BLOCK]
Typowe scenariusze błędów
„Mind Key fehlt oder ungültig"
- Pominięto nagłówek 
- Użyto , ale klucz jest błędny
- Użyto JWT tam, gdzie wymagany jest Mind Key
„Route not found"
- Zgadnięto ścieżkę, która nie istnieje
- Użyto nieprawidłowo czasownika (np.  zamiast )
- Należy sprawdzić  pod kątem poprawnych ścieżek
„Rate limit exceeded"
- Używane  i przekroczono 60 żądań/min
- Należy przełączyć się na nagłówek 
Następne kroki
- Autoryzacja
- Przegląd API
- Limity żądań