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

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

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

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

{
  "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 webhook

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

429 Too Many Requests

Ви досягли ліміту частоти. Стосується лише автентифікації через параметр запиту ?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 недійсний — попередити користувача
        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

Наступні кроки

• Автентифікація
• Огляд API
• Обмеження частоти