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) o403(rol/alcance insuficiente).
Formato de error#
Toda falla responde JSON con un mensaje en portugués y el código HTTP correspondiente:
{ "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ódigo | Significado | Causas típicas |
|---|---|---|
200 | OK | lectura exitosa |
204 | No Content | respuesta al preflight OPTIONS (CORS) |
400 | Solicitud inválida | JSON mal formado, sql ausente, $skiptoken inválido, paginación más allá del tope |
401 | No autenticado | clave ausente, inválida o revocada |
402 | Pago requerido | workspace moroso/suspendido — extracción pagada bloqueada |
403 | Prohibido | rol/alcance insuficiente, SQL que no es SELECT, referencia fuera del workspace/marts |
404 | No encontrado | EntitySet OData inexistente (también protege contra enumeración) |
429 | Demasiadas solicitudes | se superó el rate limit (incluye Retry-After) |
501 | No implementado | operación OData fuera del subconjunto soportado (filtro/opción) |
502 | Error en el datalake | falla al ejecutar la consulta |
503 | No disponible | datalake no aprovisionado, nube propia caída o limitador de solicitudes no disponible (incluye Retry-After) |
Sobre el
503del limitador: las rutas/api/v1ejecutan 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 elRetry-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):
| Bucket | Por clave | Por workspace |
|---|---|---|
Lectura (OData, tables) | 120/min | 240/min |
SQL libre (query) | 60/min | 120/min |
- Exceso →
429conRetry-After: 60. - Limitador no disponible →
503conRetry-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.
limitpredeterminado 100, máximo 1000;offsetes el desplazamiento.- La respuesta incluye
nextOffset(onullal final).
OData (server-driven):
- Páginas de hasta 1.000 filas con
@odata.nextLink; sigue el enlace exactamente (lleva un$skiptokenopaco). Token adulterado →400. Prefer: odata.maxpagesize=Nreduce la página (tope 1.000); respondePreference-Applied.- Profundidad máxima: 1.000.000 de filas por consulta; por encima →
400indicando 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 elPOST /query, que solo envía unSELECT) 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-Keyhoy (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
$metadatano disparan un job pagado. El valor enx-ingestia-cost-brles 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;
404en 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íntoma | Causa probable | Qué hacer |
|---|---|---|
402 | workspace moroso/suspendido | regulariza el pago en la app |
429 | rate limit | respeta Retry-After; reduce el paralelismo |
503 con Retry-After | limitador no disponible o datalake no aprovisionado | espera y repite; confirma el aprovisionamiento |
501 (OData) | operación fuera del subconjunto | simplifica el filtro (consulta OData) |
400 en la paginación | superaste el tope de 1M de filas o $skiptoken inválido | filtra los datos; sigue el @odata.nextLink |
Próximos pasos: API de consulta · OData/Power BI · Troubleshooting.