{"title":"Błędy i ich obsługa","slug":"errors","category":"api","summary":"Kody stanu HTTP, format odpowiedzi błędu i sposoby odzyskiwania po typowych błędach.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":493,"read_minutes":2,"llm_context":"Error format: { statusCode, error, message, docs? }\nCommon errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)\n401 → check Mind Key/JWT, see /docs/getting-started/authentication\n404 → wrong path, GET /endpoints for valid list, do NOT guess paths\n429 → rate limited (?key= is 60/min), use Bearer header instead\n500 → server error, retry with backoff, check /health\ndocs field in error response links to relevant documentation.\n","lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Błędy i ich obsługa\n\nSynapse używa standardowych kodów stanu HTTP wraz ze spójnym formatem odpowiedzi\nbłędu. Ta strona wyjaśnia, jak interpretować i obsługiwać błędy.\n\n## Format odpowiedzi błędu\n\nWszystkie błędy zwracają JSON o następującej strukturze:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n| Pole | Opis |\n|-------|-------------|\n| `statusCode` | Kod stanu HTTP |\n| `error` | Nazwa stanu HTTP |\n| `message` | Czytelny dla człowieka opis błędu |\n| `docs` | URL do istotnej dokumentacji (gdy dostępny) |\n\n## Kody stanu HTTP\n\n### 200 OK\n\nSukces. Żądanie zostało poprawnie przetworzone.\n\n### 201 Created\n\nSukces. Utworzono nowy zasób (np. `POST /memory`).\n\n### 204 No Content\n\nSukces. Brak treści w odpowiedzi (np. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nŻądanie było nieprawidłowo sformułowane. Typowe przyczyny:\n\n- Brak wymaganych pól JSON\n- Nieprawidłowa składnia JSON\n- Nieprawidłowa wartość enum (np. zła kategoria)\n\n```json\n{\n \"statusCode\": 400,\n \"error\": \"Bad Request\",\n \"message\": \"category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials\"\n}\n```\n\n**Rozwiązanie:** Należy sprawdzić treść żądania względem dokumentacji API i\nupewnić się, że wszystkie wymagane pola są obecne i mają prawidłowe wartości.\n\n### 401 Unauthorized\n\nAutoryzacja nie powiodła się. Typowe przyczyny:\n\n- Brak nagłówka `Authorization`\n- Nieprawidłowy Mind Key lub JWT\n- Użycie Mind Key tam, gdzie wymagany jest JWT (lub odwrotnie)\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n**Rozwiązanie:** Zweryfikować token. Patrz [Autoryzacja](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nUżytkownik jest uwierzytelniony, ale nie może wykonać tej akcji. Typowe przyczyny:\n\n- Próba usunięcia cudzego umysłu\n- Próba weryfikacji pamięci przy użyciu Mind Key (wymagany JWT)\n- Umysł jest wyłączony\n\n**Rozwiązanie:** Należy sprawdzić, czy używa się poprawnego typu tokena dla tego\nendpointu.\n\n### 404 Not Found\n\nŻądana ścieżka lub zasób nie istnieje.\n\n> [!CRITICAL]\n> **Nie wolno zgadywać ścieżek endpointów.** Istnieją tylko ścieżki wymienione\n> w `GET /endpoints`. W przypadku otrzymania 404 użyto błędnej ścieżki.\n\n```json\n{\n \"statusCode\": 404,\n \"error\": \"Not Found\",\n \"message\": \"Route GET /memory/list not found\",\n \"docs\": \"https://synapse.schaefer.zone/docs/api/errors\"\n}\n```\n\n**Rozwiązanie:** Wywołać `GET /endpoints`, aby zobaczyć listę poprawnych\nendpointów, i porównać swój URL z listą znak po znaku.\n\n### 409 Conflict\n\nŻądanie stoi w konflikcie z istniejącym stanem. Typowe przyczyny:\n\n- Próba rejestracji z adresem e-mail, który już istnieje\n- Duplikat URL webhooka\n\n**Rozwiązanie:** Użyć innej wartości lub użyć `PUT`, aby zaktualizować istniejący\nzasób.\n\n### 429 Too Many Requests\n\nOsiągnięto limit żądań. Dotyczy tylko autoryzacji parametrem `?key=` (60/min).\n\n```json\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\nNagłówki odpowiedzi:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Rozwiązanie:** Przełączyć się na nagłówek `Authorization: Bearer` (bez limitu)\nlub odczekać `Retry-After` sekund.\n\n### 500 Internal Server Error\n\nBłąd serwera. Nie powinien się zdarzyć — jeśli wystąpi, jest to błąd.\n\n**Rozwiązanie:**\n\n1. Ponowić z wykładniczym wycofywaniem (1 s, 2 s, 4 s, 8 s)\n2. Sprawdzić `GET /health`, aby upewnić się, że serwer działa\n3. Jeśli błąd utrzymuje się, zgłosić go\n\n### 503 Service Unavailable\n\nSerwer jest tymczasowo niedostępny (np. podczas wdrażania, migracji bazy danych).\n\n**Rozwiązanie:** Odczekać i ponowić żądanie. Sprawdzić `GET /health`.\n\n## Wzorce odzyskiwania\n\n### Ponowienie z wykładniczym wycofywaniem\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {KEY}\"})\n if r.status_code == 429:\n wait = int(r.headers.get(\"Retry-After\", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f\"Failed after {max_retries} retries\")\n```\n\n### Obsługa błędów autoryzacji\n\n```python\ndef safe_call(url, key):\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {key}\"})\n if r.status_code == 401:\n # Mind Key invalid — alert user\n raise AuthError(\"Mind Key invalid or expired\")\n return r\n```\n\n## Typowe scenariusze błędów\n\n### „Mind Key fehlt oder ungültig\"\n\n- Pominięto nagłówek `Authorization`\n- Użyto `?key=`, ale klucz jest błędny\n- Użyto JWT tam, gdzie wymagany jest Mind Key\n\n### „Route not found\"\n\n- Zgadnięto ścieżkę, która nie istnieje\n- Użyto nieprawidłowo czasownika (np. `GET /memory` zamiast `POST /memory`)\n- Należy sprawdzić `GET /endpoints` pod kątem poprawnych ścieżek\n\n### „Rate limit exceeded\"\n\n- Używane `?key=` i przekroczono 60 żądań/min\n- Należy przełączyć się na nagłówek `Authorization: Bearer`\n\n## Następne kroki\n\n- [Autoryzacja](/docs/getting-started/authentication)\n- [Przegląd API](/docs/api/overview)\n- [Limity żądań](/docs/api/rate-limits)\n","content_html":"

Błędy i ich obsługa

\n

Synapse używa standardowych kodów stanu HTTP wraz ze spójnym formatem odpowiedzi\nbłędu. Ta strona wyjaśnia, jak interpretować i obsługiwać błędy.

\n

Format odpowiedzi błędu

\n

Wszystkie błędy zwracają JSON o następującej strukturze:

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PoleOpis
statusCodeKod stanu HTTP
errorNazwa stanu HTTP
messageCzytelny dla człowieka opis błędu
docsURL do istotnej dokumentacji (gdy dostępny)
\n

Kody stanu HTTP

\n

200 OK

\n

Sukces. Żądanie zostało poprawnie przetworzone.

\n

201 Created

\n

Sukces. Utworzono nowy zasób (np. POST /memory).

\n

204 No Content

\n

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

\n

400 Bad Request

\n

Żądanie było nieprawidłowo sformułowane. Typowe przyczyny:

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

Rozwiązanie: Należy sprawdzić treść żądania względem dokumentacji API i\nupewnić się, że wszystkie wymagane pola są obecne i mają prawidłowe wartości.

\n

401 Unauthorized

\n

Autoryzacja nie powiodła się. Typowe przyczyny:

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

Rozwiązanie: Zweryfikować token. Patrz Autoryzacja.

\n

403 Forbidden

\n

Użytkownik jest uwierzytelniony, ale nie może wykonać tej akcji. Typowe przyczyny:

\n\n

Rozwiązanie: Należy sprawdzić, czy używa się poprawnego typu tokena dla tego\nendpointu.

\n

404 Not Found

\n

Żądana ścieżka lub zasób nie istnieje.

\n
**Nie wolno zgadywać ścieżek endpointów.** Istnieją tylko ścieżki wymienione\nw `GET /endpoints`. W przypadku otrzymania 404 użyto błędnej ścieżki.
{\n  "statusCode": 404,\n  "error": "Not Found",\n  "message": "Route GET /memory/list not found",\n  "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}

Rozwiązanie: Wywołać GET /endpoints, aby zobaczyć listę poprawnych\nendpointów, i porównać swój URL z listą znak po znaku.

\n

409 Conflict

\n

Żądanie stoi w konflikcie z istniejącym stanem. Typowe przyczyny:

\n\n

Rozwiązanie: Użyć innej wartości lub użyć PUT, aby zaktualizować istniejący\nzasób.

\n

429 Too Many Requests

\n

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

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

Nagłówki odpowiedzi:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42

Rozwiązanie: Przełączyć się na nagłówek Authorization: Bearer (bez limitu)\nlub odczekać Retry-After sekund.

\n

500 Internal Server Error

\n

Błąd serwera. Nie powinien się zdarzyć — jeśli wystąpi, jest to błąd.

\n

Rozwiązanie:

\n
    \n
  1. Ponowić z wykładniczym wycofywaniem (1 s, 2 s, 4 s, 8 s)
    2. \n
  2. Sprawdzić GET /health, aby upewnić się, że serwer działa
    3. \n
  3. Jeśli błąd utrzymuje się, zgłosić go
    4. \n
\n

503 Service Unavailable

\n

Serwer jest tymczasowo niedostępny (np. podczas wdrażania, migracji bazy danych).

\n

Rozwiązanie: Odczekać i ponowić żądanie. Sprawdzić GET /health.

\n

Wzorce odzyskiwania

\n

Ponowienie z wykładniczym wycofywaniem

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

Obsługa błędów autoryzacji

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

Typowe scenariusze błędów

\n

„Mind Key fehlt oder ungültig"

\n\n

„Route not found"

\n\n

„Rate limit exceeded"

\n\n

Następne kroki

\n\n","urls":{"html":"/docs/api/errors","text":"/docs/api/errors?format=text","json":"/docs/api/errors?format=json","llm":"/docs/api/errors?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}