# 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:

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

| Campo | Descripción |
|-------|-------------|
| `statusCode` | Código de estado HTTP |
| `error` | Nombre del estado HTTP |
| `message` | Descripción del error legible por humanos |
| `docs` | 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. `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)

```json
{
  "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)

```json
{
  "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](/docs/getting-started/authentication).

### 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
> `GET /endpoints`. Si obtiene un 404, usó una ruta incorrecta.

```json
{
  "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).

```json
{
  "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

```python
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

```python
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](/docs/getting-started/authentication)
- [Resumen de la API](/docs/api/overview)
- [Límites de frecuencia](/docs/api/rate-limits)