{"title":"Ошибки и обработка ошибок","slug":"errors","category":"api","summary":"HTTP-коды состояния, формат ответа с ошибкой и способы восстановления после типичных ошибок.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":480,"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":"ru","translated":true,"requested_lang":"ru","content_markdown":"\n# Ошибки и обработка ошибок\n\nSynapse использует стандартные HTTP-коды состояния с единым форматом ответа\nс ошибкой. На этой странице описано, как интерпретировать ошибки и\nвосстанавливаться после них.\n\n## Формат ответа с ошибкой\n\nВсе ошибки возвращают JSON следующей структуры:\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| Поле | Описание |\n|-------|-------------|\n| `statusCode` | HTTP-код состояния |\n| `error` | Имя HTTP-статуса |\n| `message` | Человекочитаемое описание ошибки |\n| `docs` | URL соответствующей документации (если применимо) |\n\n## HTTP-коды состояния\n\n### 200 OK\n\nУспех. Запрос обработан корректно.\n\n### 201 Created\n\nУспех. Создан новый ресурс (например, `POST /memory`).\n\n### 204 No Content\n\nУспех. Тело ответа не возвращается (например, `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nЗапрос сформирован некорректно. Типичные причины:\n\n- Отсутствуют обязательные поля JSON\n- Некорректный синтаксис JSON\n- Недопустимое значение перечисления (например, неверная категория)\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**Исправление:** Проверьте тело запроса по документации API. Убедитесь, что все\nобязательные поля присутствуют и содержат корректные значения.\n\n### 401 Unauthorized\n\nОшибка аутентификации. Типичные причины:\n\n- Отсутствует заголовок `Authorization`\n- Неверный Mind Key или JWT\n- Используется Mind Key там, где требуется JWT (или наоборот)\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**Исправление:** Проверьте ваш токен. См. [Аутентификация](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nВы аутентифицированы, но не имеете права выполнять это действие. Типичные причины:\n\n- Попытка удалить mind другого пользователя\n- Попытка подтвердить память с помощью Mind Key (требуется JWT)\n- Mind отключён\n\n**Исправление:** Убедитесь, что вы используете правильный тип токена для этого эндпоинта.\n\n### 404 Not Found\n\nЗапрошенный путь или ресурс не существует.\n\n> [!CRITICAL]\n> **Не угадывайте пути эндпоинтов.** Существуют только те пути, что перечислены\n> в `GET /endpoints`. Если вы получили 404, значит, вы использовали неверный путь.\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**Исправление:** Вызовите `GET /endpoints`, чтобы увидеть список допустимых\nэндпоинтов. Сравните ваш URL со списком посимвольно.\n\n### 409 Conflict\n\nЗапрос конфликтует с текущим состоянием. Типичные причины:\n\n- Попытка зарегистрироваться с уже существующим email\n- Дублирующийся URL вебхука\n\n**Исправление:** Используйте другое значение или примените `PUT` для обновления\nсуществующего ресурса.\n\n### 429 Too Many Requests\n\nВы превысили лимит запросов. Применяется только к аутентификации через query-параметр\n`?key=` (60 запросов в минуту).\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\nЗаголовки ответа:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Исправление:** Перейдите на заголовок `Authorization: Bearer` (без лимита)\nили подождите `Retry-After` секунд.\n\n### 500 Internal Server Error\n\nОшибка сервера. Этого не должно происходить — если произошло, это баг.\n\n**Исправление:**\n\n1. Повторите запрос с экспоненциальной задержкой (1 с, 2 с, 4 с, 8 с)\n2. Проверьте `GET /health`, чтобы убедиться, что сервер работает\n3. Если ошибка повторяется, сообщите о ней\n\n### 503 Service Unavailable\n\nСервер временно недоступен (например, во время развёртывания, миграции БД).\n\n**Исправление:** Подождите и повторите запрос. Проверьте `GET /health`.\n\n## Паттерны восстановления\n\n### Повтор с экспоненциальной задержкой\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### Обработка ошибок аутентификации\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## Типовые сценарии ошибок\n\n### \"Mind Key fehlt oder ungültig\"\n\n- Вы забыли заголовок `Authorization`\n- Вы использовали `?key=`, но ключ неверный\n- Вы используете JWT там, где требуется Mind Key\n\n### \"Route not found\"\n\n- Вы угадали несуществующий путь\n- Вы неправильно использовали HTTP-метод (например, `GET /memory` вместо `POST /memory`)\n- Проверьте `GET /endpoints` для списка допустимых путей\n\n### \"Rate limit exceeded\"\n\n- Вы используете `?key=` и превысили лимит 60 запросов в минуту\n- Перейдите на заголовок `Authorization: Bearer`\n\n## Следующие шаги\n\n- [Аутентификация](/docs/getting-started/authentication)\n- [Обзор API](/docs/api/overview)\n- [Лимиты запросов](/docs/api/rate-limits)\n","content_html":"

Ошибки и обработка ошибок

\n

Synapse использует стандартные HTTP-коды состояния с единым форматом ответа\nс ошибкой. На этой странице описано, как интерпретировать ошибки и\nвосстанавливаться после них.

\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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ПолеОписание
statusCodeHTTP-код состояния
errorИмя HTTP-статуса
messageЧеловекочитаемое описание ошибки
docsURL соответствующей документации (если применимо)
\n

HTTP-коды состояния

\n

200 OK

\n

Успех. Запрос обработан корректно.

\n

201 Created

\n

Успех. Создан новый ресурс (например, POST /memory).

\n

204 No Content

\n

Успех. Тело ответа не возвращается (например, DELETE /memory/:id).

\n

400 Bad Request

\n

Запрос сформирован некорректно. Типичные причины:

\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}

Исправление: Проверьте тело запроса по документации API. Убедитесь, что все\nобязательные поля присутствуют и содержат корректные значения.

\n

401 Unauthorized

\n

Ошибка аутентификации. Типичные причины:

\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}

Исправление: Проверьте ваш токен. См. Аутентификация.

\n

403 Forbidden

\n

Вы аутентифицированы, но не имеете права выполнять это действие. Типичные причины:

\n\n

Исправление: Убедитесь, что вы используете правильный тип токена для этого эндпоинта.

\n

404 Not Found

\n

Запрошенный путь или ресурс не существует.

\n
**Не угадывайте пути эндпоинтов.** Существуют только те пути, что перечислены\nв `GET /endpoints`. Если вы получили 404, значит, вы использовали неверный путь.
{\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}

Исправление: Вызовите GET /endpoints, чтобы увидеть список допустимых\nэндпоинтов. Сравните ваш URL со списком посимвольно.

\n

409 Conflict

\n

Запрос конфликтует с текущим состоянием. Типичные причины:

\n\n

Исправление: Используйте другое значение или примените PUT для обновления\nсуществующего ресурса.

\n

429 Too Many Requests

\n

Вы превысили лимит запросов. Применяется только к аутентификации через query-параметр\n?key= (60 запросов в минуту).

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

Заголовки ответа:

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

Исправление: Перейдите на заголовок Authorization: Bearer (без лимита)\nили подождите Retry-After секунд.

\n

500 Internal Server Error

\n

Ошибка сервера. Этого не должно происходить — если произошло, это баг.

\n

Исправление:

\n
    \n
  1. Повторите запрос с экспоненциальной задержкой (1 с, 2 с, 4 с, 8 с)
    2. \n
  2. Проверьте GET /health, чтобы убедиться, что сервер работает
    3. \n
  3. Если ошибка повторяется, сообщите о ней
    4. \n
\n

503 Service Unavailable

\n

Сервер временно недоступен (например, во время развёртывания, миграции БД).

\n

Исправление: Подождите и повторите запрос. Проверьте GET /health.

\n

Паттерны восстановления

\n

Повтор с экспоненциальной задержкой

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

Обработка ошибок аутентификации

\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

Типовые сценарии ошибок

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

Следующие шаги

\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"]}