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.
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.
{
"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`
-
codestring obligatorioUna razón estable, que una máquina puede leer. Decide con esto. Los códigos solo se agregan.
-
messagestring obligatorioQué salió mal y qué hacer, escrito para una persona, en inglés. La redacción puede cambiar: nunca la analices con código.
-
doc_urlURL obligatorioEl lugar de esta página que explica el código.
-
request_idstring obligatorioEl id de la petición. También viene en el encabezado
Sypnia-Request-Idde toda respuesta, exitosa o no. Cítalo cuando pidas ayuda. -
paramstring opcionalEl 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 - 400
invalid_body - 400
too_many_events - 401
unauthorized - 403
forbidden - 403
wrong_credential - 403
origin_not_allowed - 403
not_recordable - 403
cloud_managed - 404
not_found - 404
cloud_only - 409
conflict - 409
idempotency_conflict - 409
limit_reached - 409
ai_not_configured - 409
github_not_connected - 409
not_enough_evidence - 409
pull_request_exists - 410
expired - 413
payload_too_large - 415
unsupported_media_type - 422
session_full - 429
rate_limited - 429
limit_reached - 429
analysis_limit_reached - 429
fixes_limit_reached - 500
internal - 503
unavailable
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.
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:
{
"data": [ … ],
"next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQwOTo0OTowMloifQ"
}limitdefine 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
cursorigual anext_cursor. Deja iguales todos los demás parámetros. next_cursoresnullen 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, 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.