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
- Confira o contrato do endpoint. Ele é atômico ou aceita sucesso parcial? O Graph admite sucesso parcial; já o Sheets
spreadsheets.batchUpdatedocumenta 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. - 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.
- 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
429individual pede respeitar o limite indicado pelo provedor. Antes de reenviar, confira se o item já produziu um efeito externo. - 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.