O Synapse usa códigos de status HTTP padrão com um formato consistente de\nresposta de erro. Esta página explica como interpretar e se recuperar de erros.
\nTodos os erros retornam JSON com esta estrutura:
\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}| Campo | \nDescrição | \n
|---|---|
statusCode | \nCódigo de status HTTP | \n
error | \nNome do status HTTP | \n
message | \nDescrição do erro legível para humanos | \n
docs | \nURL para a documentação relevante (quando aplicável) | \n
Sucesso. A requisição foi processada corretamente.
\nSucesso. Um novo recurso foi criado (ex.: POST /memory).
Sucesso. Sem corpo retornado (ex.: DELETE /memory/:id).
A requisição estava malformada. Causas comuns:
\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}Correção: Confira o corpo da requisição com a documentação da API. Garanta\nque todos os campos obrigatórios estão presentes e têm valores válidos.
\nA autenticação falhou. Causas comuns:
\nAuthorization ausente{\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}Correção: Verifique seu token. Consulte Autenticação.
\nVocê está autenticado, mas não tem permissão para realizar esta ação. Causas\ncomuns:
\nCorreção: Verifique se você está usando o tipo correto de token para este\nendpoint.
\nO caminho ou recurso solicitado não existe.
\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}Correção: Chame GET /endpoints para ver a lista de endpoints válidos.\nCompare sua URL com a lista caractere por caractere.
A requisição conflita com o estado existente. Causas comuns:
\nCorreção: Use um valor diferente, ou use PUT para atualizar o recurso\nexistente.
Você atingiu um limite de taxa. Aplica-se apenas à auth via parâmetro de\nconsulta ?key= (60/min).
{\n "statusCode": 429,\n "error": "Too Many Requests",\n "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}Cabeçalhos da resposta:
\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42Correção: Mude para o cabeçalho Authorization: Bearer (sem limite de\ntaxa), ou aguarde Retry-After segundos.
Erro de servidor. Isso não deveria acontecer — se acontecer, é um bug.
\nCorreção:
\nGET /health para ver se o servidor está no arServidor temporariamente indisponível (ex.: durante deploy, migração de banco).
\nCorreção: Aguarde e tente novamente. Verifique 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 invalid — alert user\n raise AuthError("Mind Key invalid or expired")\n return rAuthorization?key= mas a chave está erradaGET /memory vs POST /memory)GET /endpoints para caminhos válidos?key= e excedeu 60 req/minAuthorization: Bearer