Integrações

# APIs assíncronas: como tentar novamente sem duplicar trabalho

Uma conexão pode falhar depois que o trabalho já começou. Projetar a integração em torno da operação torna a recuperação mais clara.

Por ApiNitro · 14 de setembro de 2026

## A primeira resposta nem sempre é o resultado

Quando uma consulta depende de uma fonte externa, manter uma conexão aberta não garante uma boa experiência. Um fluxo assíncrono permite aceitar o trabalho e recuperar seu resultado depois. Em HTTP, uma resposta 202 indica aceitação para processamento; não comprova que o trabalho terminou com sucesso.

A aplicação precisa representar essa diferença. Você pode mostrar que a solicitação foi recebida, guardar seu identificador e permitir que a pessoa continue. O estado de processamento deve se transformar em resultado ou em uma falha clara, sem exigir que o navegador permaneça aberto.

## Uma nova tentativa pertence à mesma operação

Imagine enviar uma consulta e perder a conexão antes de ler a resposta. Criar outra solicitação sem contexto pode repetir um trabalho já aceito. A idempotência permite relacionar essas tentativas à mesma intenção, conforme o contrato de integração da API.

A identidade da operação deve ser salva antes do envio e reutilizada quando a rede falhar. Se os parâmetros ou a intenção mudarem, trata-se de uma operação nova. Também é importante não deduplicar apenas porque duas consultas têm os mesmos dados: uma verificação posterior pode representar uma nova decisão legítima do usuário.

## O webhook avisa; sua aplicação executa

Um webhook permite receber uma notificação sem consultar o estado continuamente. O receptor deve verificar a autenticidade conforme a documentação de integração e registrar a entrega antes de iniciar ações de negócio. Uma mensagem recebida duas vezes não deveria iniciar o mesmo processo duas vezes.

Separar recebimento e processamento ajuda na recuperação. Seu sistema pode guardar o aviso e depois atualizar uma tarefa interna. Também deve existir um caminho para recuperar o resultado autorizado quando a notificação chega atrasada ou não pode ser entregue.

## Planeje a recuperação antes da primeira falha

Novas tentativas precisam de intervalos e de um orçamento, não de um loop imediato. Depois de uma interrupção, primeiro verifique se é possível recuperar a operação existente antes de criar outra. Preserve a relação entre solicitação, operação e resultado para investigar o fluxo sem depender de mensagens informais.

A interface pode distinguir uma consulta pendente, uma fonte que não respondeu e uma falha na entrega da notificação. São situações diferentes. Uma notificação com falha não significa necessariamente que o resultado foi perdido, nem deveria transformar um trabalho concluído em uma consulta nova.

## Aplicações e agentes dividem a responsabilidade

Um cliente REST e um agente conectado por MCP podem iniciar trabalhos semelhantes a partir de experiências diferentes. Ambos precisam de autorização, acompanhamento e uma política explícita para novas tentativas. Reconectar o cliente não deveria apagar o contexto de uma operação em andamento.

Antes de integrar, teste desconexões após o envio, notificações duplicadas e resultados demorados. Verifique o que o usuário vê e quais ações seu sistema executa em cada caso. O objetivo é recuperar a intenção original sem criar trabalho adicional por acidente.

## Fontes e leituras

-   [MDN: 202 Accepted ↗](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/202)
-   [Amazon Builders' Library: Making retries safe with idempotent APIs ↗](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)

[← Todos os artigos](https://apinitro.com/pt/artigos/)