# Помилки та обробка помилок

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

Запит є malformed. Поширені причини:

- Відсутні обов'язкові JSON-поля
- Некоректний синтаксис JSON
- Недійсне значення enum (напр. неправильна категорія)

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

**Виправлення:** Використайте інше значення або скористайтеся `PUT` для оновлення наявного ресурсу.

### 429 Too Many Requests

Ви досягли ліміту частоти. Стосується лише автентифікації через параметр запиту
`?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 недійсний — попередити користувача
        raise AuthError("Mind Key invalid or expired")
    return r
```

## Поширені сценарії помилок

### "Mind Key fehlt oder ungültig"

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

### "Route not found"

- Ви вгадали шлях, якого не існує
- Ви неправильно використали метод (напр. `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)