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

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

| Pole | Opis |
|-------|-------------|
| `statusCode` | Kod stanu HTTP |
| `error` | Nazwa stanu HTTP |
| `message` | Czytelny dla człowieka opis błędu |
| `docs` | 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. `POST /memory`).

### 204 No Content

Sukces. Brak treści w odpowiedzi (np. `DELETE /memory/:id`).

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

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"
}
```

**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 `Authorization`
- Nieprawidłowy Mind Key lub JWT
- Użycie Mind Key tam, gdzie wymagany jest JWT (lub odwrotnie)

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

**Rozwiązanie:** Zweryfikować token. Patrz [Autoryzacja](/docs/getting-started/authentication).

### 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 `GET /endpoints`. W przypadku otrzymania 404 użyto błędnej ścieżki.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}
```

**Rozwiązanie:** Wywołać `GET /endpoints`, 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ć `PUT`, aby zaktualizować istniejący
zasób.

### 429 Too Many Requests

Osiągnięto limit żądań. Dotyczy tylko autoryzacji parametrem `?key=` (60/min).

```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}
```

Nagłówki odpowiedzi:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
```

**Rozwiązanie:** Przełączyć się na nagłówek `Authorization: Bearer` (bez limitu)
lub odczekać `Retry-After` 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ć `GET /health`, 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ć `GET /health`.

## Wzorce odzyskiwania

### Ponowienie z wykładniczym wycofywaniem

```python
import time
import requests

def call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})
            if r.status_code == 429:
                wait = int(r.headers.get("Retry-After", 60))
                time.sleep(wait)
                continue
            if r.status_code >= 500:
                time.sleep(2 ** attempt)
                continue
            return r
        except requests.RequestException:
            time.sleep(2 ** attempt)
    raise Exception(f"Failed after {max_retries} retries")
```

### Obsługa błędów autoryzacji

```python
def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key invalid — alert user
        raise AuthError("Mind Key invalid or expired")
    return r
```

## Typowe scenariusze błędów

### „Mind Key fehlt oder ungültig"

- Pominięto nagłówek `Authorization`
- Użyto `?key=`, 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. `GET /memory` zamiast `POST /memory`)
- Należy sprawdzić `GET /endpoints` pod kątem poprawnych ścieżek

### „Rate limit exceeded"

- Używane `?key=` i przekroczono 60 żądań/min
- Należy przełączyć się na nagłówek `Authorization: Bearer`

## Następne kroki

- [Autoryzacja](/docs/getting-started/authentication)
- [Przegląd API](/docs/api/overview)
- [Limity żądań](/docs/api/rate-limits)