Data APIs: lo que el contrato no te dice y el sistema sí te cobrará
Data APIs: lo que el contrato no te dice y el sistema sí te cobrará
Cuando un equipo técnico evalúa una data API, el primer paso suele ser la documentación. El segundo, una prueba de concepto. El tercero, revisar el pricing. Pero hay un cuarto paso que la mayoría omite hasta que el sistema está en producción y algo falla: leer con atención el contrato de uso y sus condiciones operativas.
No es un problema de negligencia. Es que las condiciones que más duelen en producción no suelen estar en la documentación técnica. Están en los términos de servicio, en las FAQs de soporte o, directamente, en el comportamiento real del sistema bajo carga. Este post no habla de cómo elegir una API. Habla de lo que ocurre cuando ya la has elegido y las cosas dejan de funcionar como esperabas.
El SLA que parece sólido pero tiene más excepciones que garantías
Un SLA del 99,9% de disponibilidad suena bien. Son unos 8,7 horas de caída al año. Pero ¿qué cuenta como "caída"? ¿Las respuestas lentas? ¿Los timeouts parciales? ¿Los errores 503 bajo carga elevada? La mayoría de los contratos de data APIs definen la disponibilidad en términos muy concretos que suelen excluir exactamente los escenarios en los que tu sistema sufre más.
Los problemas más frecuentes no son outages totales. Son degradaciones: la API responde, pero con latencias de 8-12 segundos en lugar de 800 ms. O devuelve respuestas parciales sin error explícito. O el endpoint de búsqueda funciona, pero el de filtros avanzados está limitado a la mitad del throughput habitual.
Ninguno de esos escenarios suele activar el SLA. Pero todos rompen un pipeline de datos en producción de maneras difíciles de depurar.
Qué revisar antes de firmar:
- Cómo define el proveedor "available" vs. "degraded".
- Si existen ventanas de mantenimiento programado y con qué antelación se comunican.
- Qué compensación existe (si existe) por degradación prolongada sin outage oficial.
Rate limiting: el techo que nadie te menciona en la demo
En entornos de demostración o prueba, los límites de rate no se sienten. El volumen es bajo, las peticiones son manuales y los resultados llegan rápido. El problema aparece cuando el sistema escala.
La mayoría de data APIs documentan sus rate limits en peticiones por minuto o por hora. Pero hay dos dimensiones que suelen omitir:
Burst limits. Un proveedor puede permitir 1.000 peticiones por hora pero solo 50 peticiones en cualquier ventana de 5 segundos. Si tu sistema hace batching agresivo, vas a chocar con ese techo aunque estés dentro del límite total.
Límites por endpoint. No todos los endpoints tienen el mismo rate limit. El endpoint de consulta simple puede tener un límite holgado, pero el de agregación o el de exportación masiva puede estar 10 veces más restringido. Y eso no siempre está en la documentación principal.
La consecuencia práctica es que el equipo diseña la arquitectura pensando en el límite documentado y luego descubre en producción que hay un segundo techo que nadie mencionó.
Cambios de esquema: la deuda técnica que llega sin avisar
Una data API no es estática. Los proveedores añaden campos, deprecan otros, cambian tipos de datos o modifican la estructura de las respuestas. En teoría, el versionado debería protegerte. En la práctica, hay al menos tres situaciones habituales donde no lo hace:
- Campos opcionales que se vuelven opcionales de otra manera. Un campo que siempre devolvía un string vacío cuando no había datos empieza a devolver
null. Tu parser no lo espera. El pipeline falla silenciosamente. - Cambios en campos no versionados. Los proveedores suelen versionar los endpoints, no cada campo individual. Un cambio en la semántica de un campo (por ejemplo, cómo se calcula una métrica) no siempre genera una nueva versión del endpoint.
- Deprecaciones con ventanas cortas. Los avisos de deprecación con 30 días de antelación son frecuentes en el sector. Treinta días para que un equipo técnico con otros proyectos activos refactorice una integración es un plazo que habitualmente no se cumple.
La mitigación más efectiva no es contractual: es técnica. Schemas de validación en el ingress, alertas sobre campos inesperados y pruebas de regresión contra respuestas reales del proveedor son más fiables que confiar en que el proveedor avisará con suficiente tiempo.
Disponibilidad de datos históricos: lo que "acceso completo" realmente significa
Muchos contratos de data APIs mencionan acceso a datos históricos. La pregunta crítica es: ¿desde cuándo? ¿Con qué granularidad? ¿Con las mismas garantías de disponibilidad que los datos recientes?
En la práctica, los datos históricos en APIs de análisis tienen comportamientos distintos a los datos recientes:
- Los endpoints históricos suelen tener rate limits más restrictivos, porque el coste de computación para el proveedor es mayor.
- La completitud del histórico puede variar: un proveedor puede tener cobertura densa desde hace 18 meses y cobertura dispersa para lo anterior.
- Algunos contratos permiten acceso histórico pero no exportación masiva, lo que convierte el "acceso completo" en algo bastante más limitado cuando necesitas reconstruir una serie temporal larga.
Si tu caso de uso requiere retroalimentación histórica —auditorías, entrenamiento de modelos, benchmarking temporal— estas condiciones deben quedar explícitas antes de integrar, no después.
El modelo pay-as-you-go y la aritmética que no cierra
Los modelos de precio basados en consumo son habituales en el ecosistema de data APIs. Son razonables cuando el consumo es predecible. Se vuelven problemáticos cuando no lo es.
Los picos de señal —eventos de alto impacto mediático, crisis de reputación, lanzamientos de productos— generan exactamente el tipo de incremento de volumen que un modelo pay-as-you-go no amortigua. El sistema consume más, el coste sube, y si no hay alertas de gasto configuradas, el equipo lo descubre en la factura.
La solución no es evitar el modelo pay-as-you-go. Es instrumentarlo: presupuestos por período, alertas de umbral de consumo y una lógica de circuit breaker que limite el volumen de peticiones cuando el gasto supera un techo definido. Plataformas como FeedScale exponen métricas de consumo que permiten construir esa capa de control desde el lado del cliente, sin depender únicamente de los dashboards del proveedor.
Antes de que el sistema te cobre el aprendizaje
La integración de una data API no termina cuando el pipeline funciona. Termina cuando el equipo entiende exactamente bajo qué condiciones puede dejar de funcionar y tiene respuesta para cada uno de esos escenarios.
Eso requiere leer el contrato como un documento de riesgo, no como un trámite. Requiere probar los límites reales del sistema antes de que lo haga el tráfico de producción. Y requiere diseñar la integración asumiendo que el proveedor cambiará algo sin el aviso que prometió.
Los equipos que llegan a esa posición antes del lanzamiento no eliminan los incidentes. Los convierten en algo que ya habían previsto.