# Errores, límites, paginación

> La única forma de error y cada código de error, los límites de peticiones y sus encabezados, la paginación, los rangos de tiempo, la idempotencia, las versiones de la API y la retención.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/errors-limits-pagination/

Para agentes: Las convenciones que comparten todos los endpoints de la API de Sypnia: forma JSON del error y sus códigos, cuándo reintentar, encabezados de límite de peticiones, paginación por cursor, since/until, environment, Idempotency-Key, versiones, retención.

**\[Motor]** **\[Nube]** Estas reglas valen para todos los endpoints de la API, en un motor alojado por ti y en Sypnia Cloud.

## Errores

Todo error tiene la misma forma, y un estado HTTP que dice de qué clase es.

```json
{
  "error": {
    "code": "not_found",
    "message": "No problem with id or slug 'pay-button-does-nothin' in project 'shop'.",
    "doc_url": "https://docs.sypnia.com/api/errors-limits-pagination#not_found",
    "request_id": "req_4t7y1u9i3o5p"
  }
}
```

**Campos de \`error\`:**

- `code` (string, obligatorio): Una razón estable, que una máquina puede leer. Decide con esto. Los códigos solo se agregan.
- `message` (string, obligatorio): Qué salió mal y qué hacer, escrito para una persona, en inglés. La redacción puede cambiar: nunca la analices con código.
- `doc_url` (URL, obligatorio): El lugar de esta página que explica el código.
- `request_id` (string, obligatorio): El id de la petición. También viene en el encabezado `Sypnia-Request-Id` de toda respuesta, exitosa o no. Cítalo cuando pidas ayuda.
- `param` (string, opcional): El parámetro o el campo del cuerpo que está mal, cuando hay uno. Los campos del cuerpo usan puntos: `settings.replay.sample_rate`.

| Estado              | Qué significa                                                     | ¿Reintentar?                 |
| ------------------- | ----------------------------------------------------------------- | ---------------------------- |
| `400`               | La petición está mal                                              | No. Corrígela                |
| `401`               | No hay una credencial válida                                      | No                           |
| `403`               | La credencial no puede hacer esto                                 | No                           |
| `404`               | No existe en este proyecto                                        | No                           |
| `409`               | No encaja con el estado actual                                    | Solo después de cambiar algo |
| `410`               | Existió y ya pasó su retención                                    | No                           |
| `413`, `415`, `422` | El cuerpo es demasiado grande, del tipo equivocado, o se rechazó  | No                           |
| `429`               | Demasiadas peticiones, o se llegó a un límite                     | Sí, después de `Retry-After` |
| `500`               | El motor falló                                                    | Sí, esperando cada vez más   |
| `503`               | El motor no logra llegar a su base de datos o a su almacenamiento | Sí, después de `Retry-After` |

**Códigos de error:**

- `400` `invalid_request`: Un parámetro o el cuerpo está mal. `param` lo nombra y `message` dice qué se espera.
- `400` `invalid_body`: No se pudo leer el cuerpo: no es JSON, no es gzip válido o no tiene la forma esperada. Solo en ingesta y OTLP.
- `400` `too_many_events`: Un lote de ingesta trae más de 200 eventos.
- `401` `unauthorized`: No hay credencial, o es desconocida, revocada o vencida.
- `403` `forbidden`: La credencial es válida y no tiene el permiso que pide esta llamada, o nombra un proyecto al que no pertenece. `message` nombra el permiso que falta.
- `403` `wrong_credential`: El tipo de credencial equivocado: un token de API en un endpoint de ingesta, o una llave de ingesta en cualquier otro.
- `403` `origin_not_allowed`: Ingesta desde un navegador cuyo origen no está en `allowed_origins` del proyecto.
- `403` `not_recordable`: Un trozo de grabación o una captura de página de una ruta donde la grabación está apagada.
- `403` `cloud_managed`: Se pidió por la API algo que Sypnia Cloud maneja en la app, como crear un proyecto.
- `404` `not_found`: Eso no existe en este proyecto. También es lo que recibes por algo que existe en otro proyecto: la API nunca lo confirma.
- `404` `cloud_only`: Se llamó a un endpoint de Sypnia Cloud en un motor alojado por ti.
- `409` `conflict`: La llamada no encaja con el estado actual. `message` dice por qué.
- `409` `idempotency_conflict`: El `Idempotency-Key` ya se usó con un cuerpo distinto.
- `409` `limit_reached`: Se acabó una cantidad fija de cosas: llaves, tokens, webhooks, comprobaciones de disponibilidad.
- `409` `ai_not_configured`: La llamada necesita al agente y no hay proveedor de IA configurado, o el proyecto apagó el agente.
- `409` `github_not_connected`: Sypnia Cloud: el proyecto no tiene un repositorio conectado.
- `409` `not_enough_evidence`: Sypnia Cloud: se pidió un pull request para un problema cuyo análisis no puede justificar un arreglo.
- `409` `pull_request_exists`: Sypnia Cloud: el problema ya tiene un pull request abierto.
- `410` `expired`: El dato existió y ya pasó la retención del proyecto.
- `413` `payload_too_large`: El cuerpo supera el límite del endpoint.
- `415` `unsupported_media_type`: El `Content-Type` no es uno que el endpoint lea.
- `422` `session_full`: Un trozo de grabación para una sesión que ya tiene 720 trozos.
- `429` `rate_limited`: Demasiadas peticiones. Espera lo que diga `Retry-After`.
- `429` `limit_reached`: Solo en ingesta: el proyecto llegó a un límite de uso para este tipo de dato. La respuesta trae `slow_down`.
- `429` `analysis_limit_reached`: El proyecto usó sus análisis de hoy.
- `429` `fixes_limit_reached`: Sypnia Cloud: la organización usó los pull requests de este mes.
- `500` `internal`: El motor falló. Es un error nuestro o, en alojamiento propio, un despliegue roto: `sypnia doctor` dice cuál. Se puede reintentar.
- `503` `unavailable`: El motor no logra llegar a su base de datos o a su almacenamiento en este momento. Reintenta después de `Retry-After` (2 segundos por defecto).

### Reintentar

Reintenta `429`, `500`, `503` y las fallas de red. Espera lo que diga `Retry-After` cuando venga; si no, espera 1 segundo, luego 4, luego 15, y detente. `GET` y `DELETE` siempre se pueden repetir sin riesgo. Para `POST`, envía un [`Idempotency-Key`](#idempotency).

## Límites de peticiones

Cada token de API puede hacer **600 peticiones por minuto**. La búsqueda está limitada a 60 por minuto y `POST …/analyze` a 10 por minuto, dentro de ese mismo total. En un motor alojado por ti el número lo pones tú (`SYPNIA_RATE_LIMIT_API_PER_MINUTE`, `0` para ninguno), y se cuenta por proceso, así que un motor que corre varios procesos permite algo más.

La ingesta se limita por llave de ingesta y por dirección: 600 peticiones por minuto por defecto, y se define por llave.

Toda respuesta de la API trae:

| Encabezado            | Qué es                                               |
| --------------------- | ---------------------------------------------------- |
| `RateLimit-Limit`     | Peticiones permitidas en la ventana actual           |
| `RateLimit-Remaining` | Peticiones que quedan en la ventana                  |
| `RateLimit-Reset`     | Segundos hasta que la ventana se reinicia            |
| `Retry-After`         | Solo con `429` y `503`: segundos que hay que esperar |

Un `429 rate_limited` significa baja el ritmo y reintenta. Un `429` con otro código (`limit_reached`, `analysis_limit_reached`, `fixes_limit_reached`) significa un límite de uso: esperar unos segundos no sirve, y `Retry-After` dice cuándo se reinicia el límite.

## Paginación

Las listas devuelven una página y un cursor:

```json
{
  "data": [ … ],
  "next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQwOTo0OTowMloifQ"
}
```

- `limit` define el tamaño de la página: de 1 a 200, 50 por defecto, salvo que un endpoint diga otra cosa.
- Para traer la página siguiente, repite la misma petición con `cursor` igual a `next_cursor`. Deja iguales todos los demás parámetros.
- `next_cursor` es `null` en la última página.
- Un cursor es opaco y funciona 24 horas. Un cursor vencido o alterado es `400 invalid_request`.
- Las páginas son estables: un elemento que llega mientras paginas no corre los que todavía no has leído.

No hay números de página ni totales, salvo donde un endpoint devuelve `counts`.

## Rangos de tiempo

Los endpoints que leen a lo largo del tiempo reciben `since` y `until`.

| Forma    | Ejemplo                | Qué significa                                                         |
| -------- | ---------------------- | --------------------------------------------------------------------- |
| Relativa | `30m`, `24h`, `7d`     | Ese tiempo antes de ahora. Unidades: `m` minutos, `h` horas, `d` días |
| Absoluta | `2026-03-12T09:00:00Z` | Una fecha ISO 8601. Sin zona se lee como UTC                          |

`until` es ahora por defecto. Cada endpoint tiene su propio valor por defecto para `since`. Un rango que llega antes de la retención del proyecto se recorta a ella, sin avisar. Cuando los días importan (intervalos diarios, «hoy»), se cortan a medianoche en la zona horaria del proyecto.

## Entorno

Los endpoints de lectura reciben `environment`. El valor por defecto es `production`. Pasa cualquier nombre de entorno que tu app haya enviado, o `all`. La misma falla en dos entornos son dos problemas, así que las pruebas en `development` nunca se mezclan con producción.

## Idempotencia

Las peticiones `POST` que crean algo aceptan un encabezado `Idempotency-Key`: cualquier cadena de 1 a 255 caracteres que tú elijas, como un UUID.

- La primera respuesta para una llave se guarda 24 horas.
- La misma llave con el mismo cuerpo recibe esa respuesta otra vez, con el encabezado `Idempotent-Replayed: true`. Nada se crea dos veces.
- La misma llave con un cuerpo distinto es `409 idempotency_conflict`.

La ingesta no usa este encabezado. Un lote de eventos se puede repetir sin riesgo por su `batch_id`, y un trozo de grabación por su `seq`.

## Versiones de la API

La versión es el `/v1` de la ruta. Dentro de `v1` solo se agrega: endpoints nuevos, parámetros opcionales nuevos, campos nuevos en las respuestas, valores nuevos en las listas de valores permitidos, códigos de error nuevos. Nada se renombra ni se quita. Por eso un cliente debe ignorar los campos que no conoce y no debe fallar con un valor que no había visto.

Un cambio que rompa esto sería `/v2`, anunciado en el [registro de cambios](https://docs.sypnia.com/es/reference/changelog), y `/v1` seguiría funcionando al menos 12 meses.

Toda respuesta trae `Sypnia-Version`, la versión del motor que respondió.

## Retención

Los datos se borran cuando pasan su retención. Después, leerlos responde `410 expired`, o ya no aparecen en las listas.

| Dato                                                | Motor alojado por ti (por defecto, lo cambias tú)      | Sypnia Cloud                 |
| --------------------------------------------------- | ------------------------------------------------------ | ---------------------------- |
| Eventos, sesiones y sus líneas de tiempo, trazas    | 90 días                                                | Los días del plan            |
| Grabaciones                                         | 30 días                                                | Los días del plan, máximo 30 |
| Capturas de página                                  | 90 días                                                | Los días del plan            |
| Números por hora y por día                          | 400 días                                               | 400 días                     |
| Source maps                                         | 90 días después de la última vez que se vio la versión | Lo mismo                     |
| Problemas: frase, análisis, estado, conteos diarios | Mientras exista el proyecto                            | Mientras exista el proyecto  |

`GET /v1/usage` devuelve la retención que aplica a un proyecto.
