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:

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

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)

{
  "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)

{
  "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.

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.

{
  "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).

{
  "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

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

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
• Przegląd API
• Limity żądań