Cloudflare Workflows createBatch: migre sem perder erros

Resposta rápida

Se o seu Worker cria várias instâncias do Cloudflare Workflows, troque o array passado diretamente a createBatch() pelo novo objeto de opções. Use count quando todas as instâncias compartilham os mesmos parâmetros ou instances quando cada execução precisa de ID, parâmetros ou retenção próprios. Depois leia separadamente result.created e result.errors.

A forma antiga com array continua funcionando, mas foi descontinuada e pode omitir silenciosamente IDs que já existem ou aparecem repetidos no mesmo lote. Para obter os tipos novos em desenvolvimento local, use Wrangler 4.148.0 ou posterior e gere os tipos novamente com wrangler types.

O que mudou em 8 de outubro de 2026

A Cloudflare adicionou uma forma baseada em objeto para createBatch(). O método aceita um count de 1 a 100 ou uma lista instances de 1 a 100 entradas. O retorno passou a separar as instâncias criadas dos erros por entrada, informando posição, ID quando disponível, código e mensagem.

A mudança resolve uma limitação importante da forma antiga. Antes, IDs existentes ou repetidos eram ignorados e desapareciam do array retornado. A aplicação precisava comparar entrada e saída para perceber a ausência. No formato novo, cada item não criado aparece em errors e pode ser registrado, corrigido ou encaminhado para uma fila de revisão.

Escolha count ou instances

Use count para criar várias execuções equivalentes e deixar a plataforma gerar os IDs. É a opção adequada para tarefas homogêneas, como iniciar dez relatórios com o mesmo payload. O objeto pode incluir params compartilhados e a configuração de retenção aceita pela API.

Use instances quando cada execução representa uma entidade que precisa de identidade própria, como pedido, cliente ou arquivo. Cada entrada aceita as mesmas opções de uma criação individual. Prefira IDs determinísticos quando eles ajudam a impedir duplicação, mas trate o conflito como um resultado esperado em reprocessamentos idempotentes.

• Para execuções iguais, chame createBatch({ count: 10, params: { report: "daily" } }).
• Para execuções distintas, chame createBatch({ instances: listaDeInstancias }).
• Não envie count e instances no mesmo objeto.
• Mantenha o lote entre 1 e 100 entradas.

Como migrar o array antigo

No código antigo, a chamada createBatch(listaDeInstancias) devolve diretamente um array de WorkflowInstance. No formato novo, envolva a lista em { instances: listaDeInstancias } e desestruture { created, errors }. Qualquer código que usa o retorno como array precisa passar a percorrer created.

Atualize também testes, métricas e alertas. Um teste que apenas confere created.length pode aceitar uma perda silenciosa. Verifique que created.length mais errors.length corresponde ao total de entradas quando a chamada conclui e registre os erros com índice e ID, sem gravar payloads sensíveis.

• Atualize o Wrangler para 4.148.0 ou posterior no ambiente de desenvolvimento.
• Execute wrangler types e confira o tipo WorkflowBatchCreateResult.
• Troque createBatch(lista) por createBatch({ instances: lista }).
• Passe a consumir created no fluxo de sucesso e errors no fluxo de diagnóstico.
• Adicione um teste com ID existente e outro com ID repetido no mesmo lote.

Entenda os erros 10405 e 10415

O código 10405 indica que já existe uma instância com o ID informado. Isso pode ser um sinal normal de idempotência quando a aplicação repete deliberadamente uma solicitação, ou um conflito real quando IDs deveriam ser únicos. Decida pelo contexto do negócio; não gere outro ID automaticamente se isso puder duplicar um pagamento, envio ou processamento.

O código 10415 indica que uma entrada anterior do mesmo lote usou o mesmo ID. Somente a primeira é criada. Nesse caso, preserve o índice informado, localize as duas entradas e corrija a origem da duplicação. Repetir todo o lote sem mudar os IDs tende a produzir os mesmos conflitos.

Trate falha parcial sem repetir o que deu certo

O resultado novo permite que uma chamada crie parte do lote e reporte o restante em errors. Grave os IDs confirmados em created antes de decidir o próximo passo. Para os erros, classifique código, índice e ID e reenvie somente as entradas que realmente podem ser tentadas outra vez.

Há uma diferença importante para opções inválidas. A documentação informa que um ID inválido, uma retenção inválida ou outra opção inválida faz a chamada lançar erro antes de criar qualquer instância. Portanto, trate a exceção da chamada separadamente dos erros por item devolvidos em result.errors.

• Valide tamanho, ID, parâmetros e retenção antes de montar o lote.
• Envolva a chamada em tratamento de exceção para falhas que invalidam o lote inteiro.
• Persista ou registre created como sucesso confirmado.
• Classifique errors por código e reenvie apenas o subconjunto autorizado.
• Use uma chave idempotente para impedir efeitos duplicados quando houver retry.

O lote reduz chamadas, não o limite de criação

createBatch() reduz o número de requisições feitas à API do Workflows, mas cada instância continua contando individualmente para o limite de criação. Um lote de 100 não transforma 100 execuções em uma única unidade de cota. Se vários produtores disparam lotes ao mesmo tempo, ainda é possível atingir o limite por segundo do workflow ou da conta.

Aplique controle de concorrência, backoff com limite e uma fila quando o volume puder chegar em rajadas. Não use retry imediato para 10405 ou 10415: esses códigos descrevem conflitos de ID, não uma indisponibilidade transitória. Consulte os limites oficiais porque valores e condições podem mudar por plano e produto.

Checklist de diagnóstico

Quando algumas execuções não aparecem, comece pelo retorno de createBatch(), não apenas pelo painel. Confirme qual forma da API foi usada, a versão local do Wrangler e se o código percorre errors. Depois compare IDs, quantidade de entradas, criação confirmada e limites da plataforma.

Se toda chamada falhar, valide as opções antes de suspeitar de perda parcial. Se várias aplicações falharem ao mesmo tempo, consulte o Cloudflare Status. Se o endpoint público que inicia o lote estiver inacessível, teste DNS, TLS e HTTP separadamente para não confundir falha da rota com erro do Workflows.

• Registre horário UTC, versão implantada, quantidade do lote e um identificador de correlação.
• Confira result.created e result.errors antes de consultar cada instância.
• Procure 10405 para ID já existente e 10415 para repetição dentro do lote.
• Confirme que o lote não excede 100 entradas e que count é inteiro.
• Compare a taxa de criação com os limites do Workflows e evite repetir sucessos.

Limitações e próxima ação útil

Este guia foi verificado em 9 de outubro de 2026. A forma antiga baseada em array ainda funciona, mas está descontinuada e pode ser removida no futuro. O novo retorno melhora a observabilidade da criação; ele não garante que uma instância concluirá o workflow nem substitui status, logs, alertas e checkpoints das etapas seguintes.

Migre primeiro um ambiente de teste com um lote pequeno. Inclua uma entrada válida, um ID já existente e duas entradas com o mesmo ID. Confirme que created e errors explicam o resultado, que o retry seleciona somente o necessário e que nenhum payload sensível vai para os logs. Depois promova a mudança e acompanhe taxa de criação e falhas por código.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• Create Workflow instance batches by count or listCloudflare Changelog
• Workers API for WorkflowsCloudflare Docs
• Rules of WorkflowsCloudflare Docs
• Workflows limitsCloudflare Docs
• Cloudflare StatusCloudflare