Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Errores, límites, rate limit, paginación, idempotencia y webhooks

En esta página (12)

Página de referencia para todo lo que es común a las integraciones: formato de error, códigos HTTP, límites, rate limit, paginación, idempotencia y el estado de los webhooks.

Disponibilidad#

  • Se aplica a todas las rutas /api/v1/**. Las superficies están en estados distintos: OData y Embed = disponibles; API de consulta REST = acceso anticipado.

Permisos#

  • Consulta Autenticación. Los errores de permiso devuelven 401 (credencial) o 403 (rol/alcance insuficiente).

Formato de error#

Toda falla responde JSON con un mensaje en portugués y el código HTTP correspondiente:

json
{ "error": "Mensagem explicando o que aconteceu." }

OData agrega el encabezado OData-Version: 4.0. Las respuestas de éxito y de error llevan X-Ingestia-Access-Scope: workspace y los encabezados de CORS.

Catálogo de códigos HTTP#

CódigoSignificadoCausas típicas
200OKlectura exitosa
204No Contentrespuesta al preflight OPTIONS (CORS)
400Solicitud inválidaJSON mal formado, sql ausente, $skiptoken inválido, paginación más allá del tope
401No autenticadoclave ausente, inválida o revocada
402Pago requeridoworkspace moroso/suspendido — extracción pagada bloqueada
403Prohibidorol/alcance insuficiente, SQL que no es SELECT, referencia fuera del workspace/marts
404No encontradoEntitySet OData inexistente (también protege contra enumeración)
429Demasiadas solicitudesse superó el rate limit (incluye Retry-After)
501No implementadooperación OData fuera del subconjunto soportado (filtro/opción)
502Error en el datalakefalla al ejecutar la consulta
503No disponibledatalake no aprovisionado, nube propia caída o limitador de solicitudes no disponible (incluye Retry-After)

Sobre el 503 del limitador: las rutas /api/v1 ejecutan procesamiento pagado en el datalake. Si el servicio de rate limit deja de estar disponible, la API deniega (503) en lugar de liberar sin tope (comportamiento fail-closed). Respeta el Retry-After.

Rate limit#

Límites por ventana de 1 minuto, aplicados por clave y por workspace (una clave filtrada no supera el tope del workspace):

BucketPor clavePor workspace
Lectura (OData, tables)120/min240/min
SQL libre (query)60/min120/min
  • Exceso → 429 con Retry-After: 60.
  • Limitador no disponible → 503 con Retry-After: 60 (fail-closed).
  • Los buckets de la API están separados del BI nativo — el consumo externo no degrada la plataforma.

Paginación#

REST (/api/v1/tables/{dataset}/{table}): por limit/offset.

  • limit predeterminado 100, máximo 1000; offset es el desplazamiento.
  • La respuesta incluye nextOffset (o null al final).

OData (server-driven):

  • Páginas de hasta 1.000 filas con @odata.nextLink; sigue el enlace exactamente (lleva un $skiptoken opaco). Token adulterado → 400.
  • Prefer: odata.maxpagesize=N reduce la página (tope 1.000); responde Preference-Applied.
  • Profundidad máxima: 1.000.000 de filas por consulta; por encima → 400 indicando filtrar (cada página recorre la tabla completa en el datalake).

Idempotencia#

  • Toda la API es de solo lectura — no hay endpoint de escritura. Las solicitudes GET (y el POST /query, que solo envía un SELECT) son idempotentes por naturaleza: repetir la llamada no altera el estado.
  • Las consultas idénticas (misma versión del workspace) se sirven desde la caché con costo R$ 0; la invalidación por pipeline/DML garantiza que nunca se sirva un dato viejo.
  • No hay encabezado Idempotency-Key hoy (no es necesario sin escritura). Un mecanismo de idempotencia para operaciones de escritura solo existiría junto a una futura API de escritura (Roadmap).

Webhooks#

  • Hoy no hay una API pública de suscripción a webhooks (eventos del workspace enviados a tu endpoint) — está en el Roadmap.
  • Para reaccionar a cambios de datos hoy, usa polling del feed OData (ej.: refresh incremental en Power BI) o las suscripciones/alertas del propio producto (correo/WhatsApp, según el plan).
  • Los endpoints de webhook existentes en la plataforma son entradas internas de integración de cobro/marketing, no una API para desarrolladores.

Costo#

  • Solo la extracción de filas cuesta; autenticar, listar tablas y leer $metadata no disparan un job pagado. El valor en x-ingestia-cost-brl es una proyección.
  • LIMIT/OFFSET/paginación no reducen los bytes leídos en el datalake — filtra y agrega para pagar menos.

Seguridad#

  • Alcance por workspace en todas las rutas; PII fuera de la API; solo lectura.
  • Los errores nunca filtran credenciales ni SQL de otro workspace; 404 en un EntitySet inexistente evita la enumeración.

Límites (resumen)#

  • Página REST: máx. 1000 filas; página OData: máx. 1000; profundidad OData: máx. 1.000.000 filas/consulta.
  • Rate limit según la tabla anterior.
  • Sin API de escritura; sin webhooks públicos; clave a nivel de workspace.

Troubleshooting#

SíntomaCausa probableQué hacer
402workspace moroso/suspendidoregulariza el pago en la app
429rate limitrespeta Retry-After; reduce el paralelismo
503 con Retry-Afterlimitador no disponible o datalake no aprovisionadoespera y repite; confirma el aprovisionamiento
501 (OData)operación fuera del subconjuntosimplifica el filtro (consulta OData)
400 en la paginaciónsuperaste el tope de 1M de filas o $skiptoken inválidofiltra los datos; sigue el @odata.nextLink

Próximos pasos: API de consulta · OData/Power BI · Troubleshooting.

Enlaces relacionados