workflows

API em lote: quando HTTP 200 não confirma todos os itens

O status externo pode confirmar só o envelope. Veja como conferir resultados individuais, separar falhas e liberar o próximo passo com segurança.

Uma resposta HTTP 200 para um lote pode dizer apenas que o serviço aceitou a solicitação composta. Antes de atualizar o CRM, emitir uma mensagem ou marcar a tarefa como concluída, veja no contrato da API o que o status externo representa e confira o resultado de cada item quando a resposta os discrimina.

Resposta curta

No Microsoft Graph, um 200 na resposta do $batch não prova que todas as subsolicitações funcionaram: cada resposta interna tem seu próprio status e id. Na API do Google Sheets, o método spreadsheets.batchUpdate aplica as subsolicitações de modo atômico: uma solicitação inválida faz o lote inteiro falhar. Portanto, não use uma regra universal. Identifique a semântica do endpoint, reconcilie os IDs e só libere o próximo efeito para o que foi confirmado.

Ficha de liberação por item

Campo O que registrar sem dados sensíveis
ID enviado Chave que permite ligar pedido e resposta
Status individual Sucesso, falha recuperável, falha que exige correção ou indeterminado
Efeito confirmado Evidência do estado final na fonte de verdade, quando necessário
Próxima ação Liberar, corrigir, consultar estado, ou repetir apenas o item seguro
Responsável Pessoa que decide casos indeterminados

Regra original da Pulse: se algum item essencial estiver sem resposta correlacionável ou com efeito incerto, o resultado agregado fica pendente de reconciliação. O HTTP 200 sozinho não muda essa condição. Não inclua tokens, documentos pessoais ou o corpo completo das requisições na ficha.

Como ler o lote

  1. Confira o contrato do endpoint. Ele é atômico ou aceita sucesso parcial? O Graph admite sucesso parcial; já o Sheets spreadsheets.batchUpdate documenta aplicação atômica. Não presuma que qualquer serviço brasileiro segue um desses modelos: leia a resposta e o contrato da integração usada.
  2. Relacione pedido e resposta por ID. O Graph avisa que respostas internas podem vir em ordem diferente das solicitações. Comparar pela posição da lista pode atribuir um erro ao registro errado. Se o provedor não devolve ID, procure a correlação oficialmente documentada.
  3. Classifique sem repetir o lote inteiro. Separe sucessos, erros corrigíveis e estados desconhecidos. Um erro de permissão pede correção de acesso; um 429 individual pede respeitar o limite indicado pelo provedor. Antes de reenviar, confira se o item já produziu um efeito externo.
  4. Libere o efeito seguinte apenas para o conjunto confirmado. Se o processo exige todos os itens, bloqueie a etapa agregada até resolver a divergência. Se permite entrega parcial, registre explicitamente quais IDs avançaram e quais ficaram pendentes.

Exemplo de decisão, sem execução real

Uma equipe brasileira envia três atualizações de contatos ao Graph: A, B e C. O envelope volta 200, enquanto as respostas internas indicam sucesso de A e C e erro de permissão de B. A equipe não declara “três contatos atualizados”. Confirma A e C pela resposta individual, corrige a permissão de B e reavalia somente B. Se uma mensagem ao cliente dependia dos três registros, ela espera a reconciliação. Os IDs e resultados são fictícios; a Pulse não realizou essa integração.

Quando parar

Pare se a API não permitir relacionar item e resultado, se o endpoint puder ter efeito antes de um timeout sem oferecer consulta de estado, ou se reenviar um item puder repetir cobrança, e-mail ou criação de registro. A saída é definir fonte de verdade e tratamento manual antes de automatizar o replay.

Este guia trata resultado do lote. Se a leitura deixou itens fora por paginação, confira a cobertura das páginas. Se a falha individual for limite de chamadas, trate o 429. Se o problema for efeito repetido após reenvio, controle duplicatas.

Fontes