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:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}

Códigos de estado HTTP

200 OK

Éxito. La solicitud se procesó correctamente.

201 Created

Éxito. Se creó un nuevo recurso (p. ej. POST /memory).

204 No Content

Éxito. No se devuelve cuerpo (p. ej. DELETE /memory/:id).

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)

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"
}

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 Authorization
• Mind Key o JWT inválido
• Uso de un Mind Key donde se requiere un JWT (o viceversa)

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}

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.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}

Solución: Llame a GET /endpoints 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 PUT 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 ?key= (60/min).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}

Cabeceras de respuesta:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42

Solución: Cambie a la cabecera Authorization: Bearer (sin límite de frecuencia), o espere Retry-After 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 GET /health 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 GET /health.

Patrones de recuperación

Reintento con backoff exponencial

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")

Manejo de errores de autenticación

def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key invalid — alert user
        raise AuthError("Mind Key invalid or expired")
    return r

Escenarios de error comunes

"Mind Key fehlt oder ungültig"

• Olvidó la cabecera Authorization
• Usó ?key= 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. GET /memory vs POST /memory)
• Compruebe GET /endpoints para ver las rutas válidas

"Rate limit exceeded"

• Está usando ?key= y superó las 60 req/min
• Cambie a la cabecera Authorization: Bearer

Próximos pasos

• Autenticación
• Resumen de la API
• Límites de frecuencia