# Erros e tratamento de erros
SUMMARY: Códigos de status HTTP, formato de resposta de erro e como se recuperar de erros comuns.

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.

Erros e tratamento de erros
O Synapse usa códigos de status HTTP padrão com um formato consistente de
resposta de erro. Esta página explica como interpretar e se recuperar de erros.
Formato de resposta de erro
Todos os erros retornam JSON com esta estrutura:
[CODE BLOCK]
| Campo | Descrição |
|-------|-----------|
|  | Código de status HTTP |
|  | Nome do status HTTP |
|  | Descrição do erro legível para humanos |
|  | URL para a documentação relevante (quando aplicável) |
Códigos de status HTTP
200 OK
Sucesso. A requisição foi processada corretamente.
201 Created
Sucesso. Um novo recurso foi criado (ex.: ).
204 No Content
Sucesso. Sem corpo retornado (ex.: ).
400 Bad Request
A requisição estava malformada. Causas comuns:
- Campos JSON obrigatórios ausentes
- Sintaxe JSON inválida
- Valor de enum inválido (ex.: categoria errada)
[CODE BLOCK]
Correção: Confira o corpo da requisição com a documentação da API. Garanta
que todos os campos obrigatórios estão presentes e têm valores válidos.
401 Unauthorized
A autenticação falhou. Causas comuns:
- Cabeçalho  ausente
- Mind Key ou JWT inválido
- Uso de Mind Key onde JWT é necessário (ou vice-versa)
[CODE BLOCK]
Correção: Verifique seu token. Consulte Autenticação.
403 Forbidden
Você está autenticado, mas não tem permissão para realizar esta ação. Causas
comuns:
- Tentativa de excluir o mind de outro usuário
- Tentativa de verificar uma memória com Mind Key (requer JWT)
- Mind desativado
Correção: Verifique se você está usando o tipo correto de token para este
endpoint.
404 Not Found
O caminho ou recurso solicitado não existe.
> [!CRITICAL]
> NÃO tente adivinhar caminhos de endpoint. Apenas os caminhos listados em
>  existem. Se você recebeu um 404, usou um caminho errado.
[CODE BLOCK]
Correção: Chame  para ver a lista de endpoints válidos.
Compare sua URL com a lista caractere por caractere.
409 Conflict
A requisição conflita com o estado existente. Causas comuns:
- Tentativa de registrar com um email que já existe
- URL de webhook duplicada
Correção: Use um valor diferente, ou use  para atualizar o recurso
existente.
429 Too Many Requests
Você atingiu um limite de taxa. Aplica-se apenas à auth via parâmetro de
consulta  (60/min).
[CODE BLOCK]
Cabeçalhos da resposta:
[CODE BLOCK]
Correção: Mude para o cabeçalho  (sem limite de
taxa), ou aguarde  segundos.
500 Internal Server Error
Erro de servidor. Isso não deveria acontecer — se acontecer, é um bug.
Correção:
1. Faça retry com backoff exponencial (1s, 2s, 4s, 8s)
2. Verifique  para ver se o servidor está no ar
3. Se persistir, relate o erro
503 Service Unavailable
Servidor temporariamente indisponível (ex.: durante deploy, migração de banco).
Correção: Aguarde e tente novamente. Verifique .
Padrões de recuperação
Retry com backoff exponencial
[CODE BLOCK]
Tratamento de erro de auth
[CODE BLOCK]
Cenários comuns de erro
"Mind Key fehlt oder ungültig"
- Você esqueceu o cabeçalho 
- Você usou  mas a chave está errada
- Você está usando um JWT onde uma Mind Key é necessária
"Route not found"
- Você tentou adivinhar um caminho que não existe
- Você usou um verbo errado (ex.:  vs )
- Confira  para caminhos válidos
"Rate limit exceeded"
- Você está usando  e excedeu 60 req/min
- Mude para o cabeçalho 
Próximos passos
- Autenticação
- Visão geral da API
- Limites de taxa