Synapse використовує стандартні коди стану HTTP із послідовним форматом\nвідповідей з помилками. Ця сторінка пояснює, як інтерпретувати та відновлюватися\nпісля помилок.
\nУсі помилки повертають JSON такої структури:
\n{\n "statusCode": 401,\n "error": "Unauthorized",\n "message": "Mind Key fehlt oder ungültig.",\n "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}| Поле | \nОпис | \n
|---|---|
statusCode | \nКод стану HTTP | \n
error | \nНазва статусу HTTP | \n
message | \nЗрозумілий для людини опис помилки | \n
docs | \nURL-адреса відповідної документації (за наявності) | \n
Успіх. Запит оброблено коректно.
\nУспіх. Створено новий ресурс (напр. POST /memory).
Успіх. Тіло відповіді не повертається (напр. DELETE /memory/:id).
Запит є malformed. Поширені причини:
\n{\n "statusCode": 400,\n "error": "Bad Request",\n "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"\n}Виправлення: Перевірте тіло запиту за документацією API. Переконайтеся, що\nусі обов'язкові поля присутні та мають коректні значення.
\nПомилка автентифікації. Поширені причини:
\nAuthorization{\n "statusCode": 401,\n "error": "Unauthorized",\n "message": "Mind Key fehlt oder ungültig.",\n "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}Виправлення: Перевірте ваш токен. Дивіться Автентифікацію.
\nВи автентифіковані, але не маєте права виконувати цю дію. Поширені причини:
\nВиправлення: Перевірте, чи використовуєте правильний тип токена для цієї кінцевої точки.
\nЗапитаний шлях або ресурс не існує.
\n{\n "statusCode": 404,\n "error": "Not Found",\n "message": "Route GET /memory/list not found",\n "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}Виправлення: Викличте GET /endpoints, щоб побачити список дійсних кінцевих\nточок. Порівняйте ваш URL зі списком символ за символом.
Запит конфліктує з наявним станом. Поширені причини:
\nВиправлення: Використайте інше значення або скористайтеся PUT для оновлення наявного ресурсу.
Ви досягли ліміту частоти. Стосується лише автентифікації через параметр запиту\n?key= (60/хв).
{\n "statusCode": 429,\n "error": "Too Many Requests",\n "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}Заголовки відповіді:
\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42Виправлення: Перейдіть на заголовок Authorization: Bearer (без обмеження\nчастоти) або зачекайте Retry-After секунд.
Помилка сервера. Це не повинно траплятися — якщо трапилося, це баг.
\nВиправлення:
\nGET /health, щоб переконатися, що сервер працюєСервер тимчасово недоступний (напр. під час розгортання, міграції БД).
\nВиправлення: Зачекайте та повторіть спробу. Перевірте GET /health.
import time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})\n if r.status_code == 429:\n wait = int(r.headers.get("Retry-After", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f"Failed after {max_retries} retries")def safe_call(url, key):\n r = requests.get(url, headers={"Authorization": f"Bearer {key}"})\n if r.status_code == 401:\n # Mind Key недійсний — попередити користувача\n raise AuthError("Mind Key invalid or expired")\n return rAuthorization?key=, але ключ неправильнийGET /memory замість POST /memory)GET /endpoints для дійсних шляхів?key= та перевищили 60 запитів/хвAuthorization: Bearer