Docs

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 MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Errores
  2. Reintentar
  3. Límites de peticiones
  4. Paginación
  5. Rangos de tiempo
  6. Entorno
  7. Idempotencia
  8. Versiones de la API
  9. 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.

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

Códigos de error

  • 400invalid_request

    Un parámetro o el cuerpo está mal. param lo nombra y message dice qué se espera.

  • 400invalid_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.

  • 400too_many_events

    Un lote de ingesta trae más de 200 eventos.

  • 401unauthorized

    No hay credencial, o es desconocida, revocada o vencida.

  • 403forbidden

    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.

  • 403wrong_credential

    El tipo de credencial equivocado: un token de API en un endpoint de ingesta, o una llave de ingesta en cualquier otro.

  • 403origin_not_allowed

    Ingesta desde un navegador cuyo origen no está en allowed_origins del proyecto.

  • 403not_recordable

    Un trozo de grabación o una captura de página de una ruta donde la grabación está apagada.

  • 403cloud_managed

    Se pidió por la API algo que Sypnia Cloud maneja en la app, como crear un proyecto.

  • 404not_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.

  • 404cloud_only

    Se llamó a un endpoint de Sypnia Cloud en un motor alojado por ti.

  • 409conflict

    La llamada no encaja con el estado actual. message dice por qué.

  • 409idempotency_conflict

    El Idempotency-Key ya se usó con un cuerpo distinto.

  • 409limit_reached

    Se acabó una cantidad fija de cosas: llaves, tokens, webhooks, comprobaciones de disponibilidad.

  • 409ai_not_configured

    La llamada necesita al agente y no hay proveedor de IA configurado, o el proyecto apagó el agente.

  • 409github_not_connected

    Sypnia Cloud: el proyecto no tiene un repositorio conectado.

  • 409not_enough_evidence

    Sypnia Cloud: se pidió un pull request para un problema cuyo análisis no puede justificar un arreglo.

  • 409pull_request_exists

    Sypnia Cloud: el problema ya tiene un pull request abierto.

  • 410expired

    El dato existió y ya pasó la retención del proyecto.

  • 413payload_too_large

    El cuerpo supera el límite del endpoint.

  • 415unsupported_media_type

    El Content-Type no es uno que el endpoint lea.

  • 422session_full

    Un trozo de grabación para una sesión que ya tiene 720 trozos.

  • 429rate_limited

    Demasiadas peticiones. Espera lo que diga Retry-After.

  • 429limit_reached

    Solo en ingesta: el proyecto llegó a un límite de uso para este tipo de dato. La respuesta trae slow_down.

  • 429analysis_limit_reached

    El proyecto usó sus análisis de hoy.

  • 429fixes_limit_reached

    Sypnia Cloud: la organización usó los pull requests de este mes.

  • 500internal

    El motor falló. Es un error nuestro o, en alojamiento propio, un despliegue roto: sypnia doctor dice cuál. Se puede reintentar.

  • 503unavailable

    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.

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:

EncabezadoQué es
RateLimit-LimitPeticiones permitidas en la ventana actual
RateLimit-RemainingPeticiones que quedan en la ventana
RateLimit-ResetSegundos hasta que la ventana se reinicia
Retry-AfterSolo 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.

FormaEjemploQué significa
Relativa30m, 24h, 7dEse tiempo antes de ahora. Unidades: m minutos, h horas, d días
Absoluta2026-03-12T09:00:00ZUna 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.

DatoMotor alojado por ti (por defecto, lo cambias tú)Sypnia Cloud
Eventos, sesiones y sus líneas de tiempo, trazas90 díasLos días del plan
Grabaciones30 díasLos días del plan, máximo 30
Capturas de página90 díasLos días del plan
Números por hora y por día400 días400 días
Source maps90 días después de la última vez que se vio la versiónLo mismo
Problemas: frase, análisis, estado, conteos diariosMientras exista el proyectoMientras exista el proyecto

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

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar