# Помилки та обробка помилок
SUMMARY: Коди стану HTTP, формат відповідей з помилками та способи відновлення після поширених помилок.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

Помилки та обробка помилок
Synapse використовує стандартні коди стану HTTP із послідовним форматом
відповідей з помилками. Ця сторінка пояснює, як інтерпретувати та відновлюватися
після помилок.
Формат відповіді з помилкою
Усі помилки повертають JSON такої структури:
[CODE BLOCK]
| Поле | Опис |
|-------|-------------|
|  | Код стану HTTP |
|  | Назва статусу HTTP |
|  | Зрозумілий для людини опис помилки |
|  | URL-адреса відповідної документації (за наявності) |
Коди стану HTTP
200 OK
Успіх. Запит оброблено коректно.
201 Created
Успіх. Створено новий ресурс (напр. ).
204 No Content
Успіх. Тіло відповіді не повертається (напр. ).
400 Bad Request
Запит є malformed. Поширені причини:
- Відсутні обов'язкові JSON-поля
- Некоректний синтаксис JSON
- Недійсне значення enum (напр. неправильна категорія)
[CODE BLOCK]
Виправлення: Перевірте тіло запиту за документацією API. Переконайтеся, що
усі обов'язкові поля присутні та мають коректні значення.
401 Unauthorized
Помилка автентифікації. Поширені причини:
- Відсутній заголовок 
- Недійсний Mind Key або JWT
- Використання Mind Key там, де потрібен JWT (або навпаки)
[CODE BLOCK]
Виправлення: Перевірте ваш токен. Дивіться Автентифікацію.
403 Forbidden
Ви автентифіковані, але не маєте права виконувати цю дію. Поширені причини:
- Спроба видалити чужий mind
- Спроба верифікувати спогад за допомогою Mind Key (потрібен JWT)
- Mind вимкнено
Виправлення: Перевірте, чи використовуєте правильний тип токена для цієї кінцевої точки.
404 Not Found
Запитаний шлях або ресурс не існує.
> [!CRITICAL]
> НЕ вгадуйте шляхи кінцевих точок. Існують лише шляхи зі списку .
> Якщо отримали 404 — ви використали неправильний шлях.
[CODE BLOCK]
Виправлення: Викличте , щоб побачити список дійсних кінцевих
точок. Порівняйте ваш URL зі списком символ за символом.
409 Conflict
Запит конфліктує з наявним станом. Поширені причини:
- Спроба зареєструватися з email, що вже існує
- Дублікат URL webhook
Виправлення: Використайте інше значення або скористайтеся  для оновлення наявного ресурсу.
429 Too Many Requests
Ви досягли ліміту частоти. Стосується лише автентифікації через параметр запиту
 (60/хв).
[CODE BLOCK]
Заголовки відповіді:
[CODE BLOCK]
Виправлення: Перейдіть на заголовок  (без обмеження
частоти) або зачекайте  секунд.
500 Internal Server Error
Помилка сервера. Це не повинно траплятися — якщо трапилося, це баг.
Виправлення:
1. Повторіть із експоненційною затримкою (1с, 2с, 4с, 8с)
2. Перевірте , щоб переконатися, що сервер працює
3. Якщо помилка стійка, повідомте про неї
503 Service Unavailable
Сервер тимчасово недоступний (напр. під час розгортання, міграції БД).
Виправлення: Зачекайте та повторіть спробу. Перевірте .
Шаблони відновлення
Повтор із експоненційною затримкою
[CODE BLOCK]
Обробка помилок автентифікації
[CODE BLOCK]
Поширені сценарії помилок
"Mind Key fehlt oder ungültig"
- Ви забули заголовок 
- Ви використали , але ключ неправильний
- Ви використовуєте JWT там, де потрібен Mind Key
"Route not found"
- Ви вгадали шлях, якого не існує
- Ви неправильно використали метод (напр.  замість )
- Перевірте  для дійсних шляхів
"Rate limit exceeded"
- Ви використовуєте  та перевищили 60 запитів/хв
- Перейдіть на заголовок 
Наступні кроки
- Автентифікація
- Огляд API
- Обмеження частоти