Erros, limites, rate limit, paginação, idempotência e webhooks

Selo de estado: Preview — referência dos contratos transversais das rotas /api/v1/**. Atualizado em 2026-09-06.

Página de referência para tudo que é comum às integrações: formato de erro, códigos HTTP, limites, rate limit, paginação, idempotência e o estado dos webhooks.

Disponibilidade#

• Aplica-se a todas as rotas /api/v1/**. As superfícies estão em estados distintos: OData e Embed = Preview; API de consulta REST = fora de GA.

Permissões#

• Ver Autenticação. Erros de permissão retornam 401 (credencial) ou 403 (papel/escopo insuficiente).

Formato de erro#

Toda falha responde JSON com uma mensagem em português e o código HTTP correspondente:

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

O OData acrescenta o cabeçalho OData-Version: 4.0. Respostas de sucesso e de erro trazem X-Ingestia-Access-Scope: workspace e os cabeçalhos de CORS.

Catálogo de códigos HTTP#

Sobre o 503 do limitador: as rotas /api/v1 executam processamento pago no datalake. Se o serviço de rate limit ficar indisponível, a API nega (503) em vez de liberar sem teto (comportamento fail-closed). Respeite o Retry-After.

Rate limit#

Limites por janela de 1 minuto, aplicados por chave e por workspace (uma chave vazada não fura o teto do workspace):

• Estouro → 429 com Retry-After: 60.
• Limitador indisponível → 503 com Retry-After: 60 (fail-closed).
• Os buckets de API são separados do BI nativo — consumo externo não degrada a plataforma.

Paginação#

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

• limit padrão 100, máximo 1000; offset é o deslocamento.
• A resposta traz nextOffset (ou null no fim).

OData (server-driven):

• Páginas de até 1.000 linhas com @odata.nextLink; siga o link exatamente (carrega um $skiptoken opaco). Token adulterado → 400.
• Prefer: odata.maxpagesize=N reduz a página (teto 1.000); responde Preference-Applied.
• Profundidade máxima: 1.000.000 de linhas por consulta; acima → 400 orientando a filtrar (cada página varre a tabela inteira no datalake).

Idempotência#

• Toda a API é somente leitura — não há endpoint de escrita. Requisições GET (e o POST /query, que só envia um SELECT) são idempotentes por natureza: repetir a chamada não altera estado.
• Consultas idênticas (mesma versão do workspace) servem do cache com custo R$ 0; a invalidação por pipeline/DML garante que nunca se serve dado velho.
• Não há cabeçalho Idempotency-Key hoje (não é necessário sem escrita). Um mecanismo de idempotência para operações de escrita só existiria junto de uma futura API de escrita (Roadmap).

Webhooks#

• Não há, hoje, uma API pública de assinatura de webhooks (eventos do workspace enviados ao seu endpoint) — está no Roadmap.
• Para reagir a mudanças de dados hoje, use polling do feed OData (ex.: refresh incremental no Power BI) ou as assinaturas/alertas do próprio produto (e-mail/WhatsApp, conforme o plano).
• Os endpoints de webhook existentes na plataforma são entradas internas de integração de cobrança/marketing, não uma API para desenvolvedores.

Custo#

• Só extração de linhas custa; autenticar, listar tabelas e ler $metadata não disparam job pago. O valor em x-ingestia-cost-brl é uma projeção.
• LIMIT/OFFSET/paginação não reduzem bytes lidos no datalake — filtre e agregue para pagar menos.

Segurança#

• Escopo por workspace em todas as rotas; PII fora da API; somente leitura.
• Erros nunca vazam credenciais nem SQL de outro workspace; 404 em EntitySet inexistente evita enumeração.

Limites (resumo)#

• Página REST: máx 1000 linhas; página OData: máx 1000; profundidade OData: máx 1.000.000 linhas/consulta.
• Rate limit conforme a tabela acima.
• Sem API de escrita; sem webhooks públicos; chave de nível workspace.

Troubleshooting#

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

Estado & evidência: contratos transversais das rotas /api/v1 (rate limit fail-closed, paginação, formato de erro). Fonte: matriz de estados do produto.