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

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

Формат ответа с ошибкой

Все ошибки возвращают JSON следующей структуры:

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

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

200 OK

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

201 Created

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

204 No Content

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

400 Bad Request

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

• Отсутствуют обязательные поля JSON
• Некорректный синтаксис JSON
• Недопустимое значение перечисления (например, неверная категория)

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

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

401 Unauthorized

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

• Отсутствует заголовок Authorization
• Неверный Mind Key или JWT
• Используется Mind Key там, где требуется JWT (или наоборот)

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

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

403 Forbidden

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

• Попытка удалить mind другого пользователя
• Попытка подтвердить память с помощью Mind Key (требуется JWT)
• Mind отключён

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

404 Not Found

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

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

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

409 Conflict

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

• Попытка зарегистрироваться с уже существующим email
• Дублирующийся URL вебхука

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

429 Too Many Requests

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

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

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

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

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

500 Internal Server Error

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

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

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

503 Service Unavailable

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

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

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

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

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

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

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

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

"Mind Key fehlt oder ungültig"

• Вы забыли заголовок Authorization
• Вы использовали ?key=, но ключ неверный
• Вы используете JWT там, где требуется Mind Key

"Route not found"

• Вы угадали несуществующий путь
• Вы неправильно использовали HTTP-метод (например, GET /memory вместо POST /memory)
• Проверьте GET /endpoints для списка допустимых путей

"Rate limit exceeded"

• Вы используете ?key= и превысили лимит 60 запросов в минуту
• Перейдите на заголовок Authorization: Bearer

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

• Аутентификация
• Обзор API
• Лимиты запросов