# Errores y manejo de errores
SUMMARY: Códigos de estado HTTP, formato de respuesta de error y cómo recuperarse de errores comunes.

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.

Errores y manejo de errores
Synapse utiliza códigos de estado HTTP estándar con un formato de respuesta de
error consistente. Esta página explica cómo interpretar y recuperarse de los
errores.
Formato de respuesta de error
Todos los errores devuelven JSON con esta estructura:
[CODE BLOCK]
| Campo | Descripción |
|-------|-------------|
|  | Código de estado HTTP |
|  | Nombre del estado HTTP |
|  | Descripción del error legible por humanos |
|  | URL a la documentación relevante (cuando aplica) |
Códigos de estado HTTP
200 OK
Éxito. La solicitud se procesó correctamente.
201 Created
Éxito. Se creó un nuevo recurso (p. ej. ).
204 No Content
Éxito. No se devuelve cuerpo (p. ej. ).
400 Bad Request
La solicitud estaba mal formada. Causas comunes:
- Faltan campos JSON obligatorios
- Sintaxis JSON inválida
- Valor de enum inválido (p. ej. categoría incorrecta)
[CODE BLOCK]
Solución: Verifique el cuerpo de la solicitud contra la documentación de la
API. Asegúrese de que todos los campos obligatorios estén presentes y tengan
valores válidos.
401 Unauthorized
Falló la autenticación. Causas comunes:
- Falta la cabecera 
- Mind Key o JWT inválido
- Uso de un Mind Key donde se requiere un JWT (o viceversa)
[CODE BLOCK]
Solución: Verifique su token. Consulte Autenticación.
403 Forbidden
Está autenticado pero no se le permite realizar esta acción. Causas comunes:
- Intentar eliminar el mind de otro usuario
- Intentar verificar una memoria con un Mind Key (requiere JWT)
- El mind está deshabilitado
Solución: Compruebe si está usando el tipo de token correcto para este
endpoint.
404 Not Found
La ruta o recurso solicitado no existe.
> [!CRITICAL]
> NO adivine las rutas de los endpoints. Solo existen las rutas listadas en
> . Si obtiene un 404, usó una ruta incorrecta.
[CODE BLOCK]
Solución: Llame a  para ver la lista de endpoints válidos.
Compare su URL contra la lista carácter por carácter.
409 Conflict
La solicitud entra en conflicto con el estado existente. Causas comunes:
- Intentar registrarse con un email que ya existe
- URL de webhook duplicada
Solución: Use un valor diferente, o use  para actualizar el recurso
existente.
429 Too Many Requests
Alcanzó un límite de frecuencia. Solo aplica a la autenticación por parámetro de
consulta  (60/min).
[CODE BLOCK]
Cabeceras de respuesta:
[CODE BLOCK]
Solución: Cambie a la cabecera  (sin límite de
frecuencia), o espere  segundos.
500 Internal Server Error
Error del servidor. Esto no debería ocurrir — si ocurre, es un bug.
Solución:
1. Reintente con backoff exponencial (1s, 2s, 4s, 8s)
2. Compruebe  para ver si el servidor está activo
3. Si persiste, reporte el error
503 Service Unavailable
El servidor está temporalmente inactivo (p. ej. durante un despliegue, migración
de base de datos).
Solución: Espere y reintente. Compruebe .
Patrones de recuperación
Reintento con backoff exponencial
[CODE BLOCK]
Manejo de errores de autenticación
[CODE BLOCK]
Escenarios de error comunes
"Mind Key fehlt oder ungültig"
- Olvidó la cabecera 
- Usó  pero la clave es incorrecta
- Está usando un JWT donde se requiere un Mind Key
"Route not found"
- Adivinó una ruta que no existe
- Usó un verbo incorrecto (p. ej.  vs )
- Compruebe  para ver las rutas válidas
"Rate limit exceeded"
- Está usando  y superó las 60 req/min
- Cambie a la cabecera 
Próximos pasos
- Autenticación
- Resumen de la API
- Límites de frecuencia