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

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

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

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

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

| Поле | Описание |
|-------|-------------|
| `statusCode` | HTTP-код состояния |
| `error` | Имя HTTP-статуса |
| `message` | Человекочитаемое описание ошибки |
| `docs` | URL соответствующей документации (если применимо) |

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

### 200 OK

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

### 201 Created

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

### 204 No Content

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

### 400 Bad Request

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

- Отсутствуют обязательные поля JSON
- Некорректный синтаксис 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 (или наоборот)

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

**Исправление:** Проверьте ваш токен. См. [Аутентификация](/docs/getting-started/authentication).

### 403 Forbidden

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

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

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

### 404 Not Found

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

> [!CRITICAL]
> **Не угадывайте пути эндпоинтов.** Существуют только те пути, что перечислены
> в `GET /endpoints`. Если вы получили 404, значит, вы использовали неверный путь.

```json
{
  "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 запросов в минуту).

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

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

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

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

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

```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
```

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

### "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`

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

- [Аутентификация](/docs/getting-started/authentication)
- [Обзор API](/docs/api/overview)
- [Лимиты запросов](/docs/api/rate-limits)