Códigos HTTP, 120/min, paginação, idempotência

Selo de estado: Preview (teto atual do produto) · Curso ACD-250 — Integrações e consumo externo · Aula 5 de 6 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai diagnosticar 429 com Retry-After — e distinguir, pelo código HTTP, o que é seu erro, o que é teto de requisição, o que é dinheiro e o que é indisponibilidade proposital.

Vídeo#

Identificador no manifesto: acd-250-05-erros-rate-limit-idempotencia · duração-alvo 6 min · tela do produto: /connect.

Roteiro de gravação (5 capítulos):

Conteúdo#

Esta é a aula dos contratos transversais — o que vale para todas as rotas /api/v1/**, independentemente da superfície. É aula de conhecimento porque não há nada para configurar: o que existe aqui é a capacidade de ler uma resposta de erro e saber o que fazer.

Começa com uma boa notícia: há um formato de erro para tudo.

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

Sempre JSON, sempre com mensagem em português, sempre com o código HTTP correspondente. As respostas — de sucesso e de erro — carregam X-Ingestia-Access-Scope: workspace, lembrete de que a credencial lê o workspace inteiro; o OData acrescenta OData-Version: 4.0.

O catálogo, em quatro famílias

Ler por família acelera o diagnóstico: 400/404/501 você corrige na sua requisição; 401/403 você corrige na credencial (Aula 2); 402 é a regra do dinheiro; 429/503 você espera, não insiste.

Rate limit: 120/min, e o 503 que protege o seu bolso

Os limites são por janela de 1 minuto, aplicados por chave e por workspace — assim uma chave vazada não fura o teto do workspace:

Estourou? 429 com Retry-After: 60. O comportamento correto do cliente é simples e quase sempre feito errado: leia o Retry-After e espere o que ele diz, em vez de tentar de novo imediatamente. Reduzir paralelismo resolve mais do que repetir.

Agora a parte contraintuitiva e a mais importante desta aula. Se o serviço de rate limit ficar indisponível, a API nega com 503 em vez de liberar sem teto. Chama-se fail-closed, e a razão é econômica: as rotas /api/v1 executam BigQuery pago. Liberar sem limitador seria arriscar fatura ilimitada em nome da disponibilidade. O produto escolhe recusar.

Um detalhe que tranquiliza: os buckets da API são separados do BI nativo. Consumo externo pesado via Power BI não degrada o BI dentro do produto.

Paginação

Duas formas, porque são duas superfícies:

• OData (Preview, Aula 3): server-driven, páginas de até 1.000 linhas com @odata.nextLink; siga o link exatamente (ele carrega um $skiptoken opaco — token adulterado responde 400). Prefer: odata.maxpagesize=N reduz a página (teto 1.000) e a resposta confirma com Preference-Applied. Profundidade máxima: 1.000.000 de linhas por consulta; acima, 400 orientando a filtrar.
• REST (/api/v1/tables/{dataset}/{table}, fora de GA, Aula 6): limit (padrão 100, máximo 1000) e offset, com nextOffset na resposta — null no fim.

E a regra de custo que vale para as duas: LIMIT, OFFSET e paginação não reduzem bytes lidos no BigQuery. Para pagar menos, filtre e agregue.

Idempotência: a resposta curta é "a API é somente leitura"

Não existe endpoint de escrita no ingestia.io. Toda rota é GET — ou POST apenas para enviar um SELECT. Logo, as chamadas são idempotentes por natureza: repetir não altera estado. Não há cabeçalho Idempotency-Key, e não é esquecimento: sem escrita, ele não tem o que proteger. Um mecanismo de idempotência só faria sentido junto de uma futura API de escrita, que é Roadmap.

Como bônus, consultas idênticas (mesma versão do workspace) servem do cache com custo R$ 0, e a invalidação por pipeline garante que nunca se serve dado velho.

Webhooks: não existem hoje

Não há 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, há dois caminhos legítimos: consulta periódica do feed OData (a atualização incremental do Power BI é exatamente isso) ou as assinaturas e alertas do próprio produto, conforme o plano. Os endpoints de webhook que existem na plataforma são entradas internas de cobrança e marketing, não uma API para desenvolvedores.

Exemplo: a Aurora Varejo às 6h

O servidor de integração da Aurora dispara 40 atualizações de Power BI em paralelo às 6h. Na terceira, começam a chover 429 com Retry-After: 60. O time lê o cabeçalho e descobre o óbvio: 40 refreshes paralelos, cada um paginando várias páginas, passam fácil de 120 chamadas no minuto com a mesma chave. A correção tem duas partes: escalonar os refreshes ao longo de 15 minutos e filtrar por janela de data para que cada um faça menos páginas. Semanas depois aparece um 503 com Retry-After num horário aleatório — o limitador estava indisponível, e a API negou de propósito para não rodar consulta cobrável sem teto. A resposta certa foi esperar, não repetir em laço.

Erros comuns

Faça você mesmo#

Esta aula é de conhecimento: não há exercício operacional. Leia, assista e responda à checagem rápida.

Para fixar sem operar nada, faça o exercício de mesa: pegue os sete códigos da tabela de erros comuns e, para cada um, escreva numa linha de quem é o problema (seu, da credencial, do dinheiro ou da plataforma) e qual é a primeira ação. Depois dimensione no papel quantas chamadas por minuto a sua integração faria no pior horário, e compare com 120/min por chave. Em nenhum momento tente provocar 429 de propósito contra a rota /api/v1/query — ela está fora de GA e não deve receber tráfego seu (Aula 6).

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• desenvolvedores/erros-limites-rate-limit

Capacidades ensinadas#

(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".