Retentativas em APIs de IA: como se recuperar de falhas sem duplicar solicitações nem custos

Uma retentativa não é uma repetição inofensiva

Fazer uma retentativa significa enviar uma solicitação novamente depois que uma tentativa anterior não produziu uma resposta utilizável para o cliente. A dificuldade é que «não recebi uma resposta» não equivale necessariamente a «o servidor não processou a solicitação». A conexão pode ser interrompida antes do envio, durante a transmissão ou depois de o serviço receber e executar a solicitação. Neste último caso, repeti-la pode iniciar uma segunda operação ou gerar uma segunda cobrança, embora o cliente só tenha visto um erro de rede.

Por isso, uma política útil começa antes de escolher uma pausa entre tentativas. É preciso saber qual operação está sendo repetida, que resultado é conhecido, que resultado é incerto e quanto esforço adicional é permitido. Uma nova consulta sem efeitos externos e uma operação que inicia uma tarefa, consome recursos ou altera o estado não apresentam o mesmo risco. Também não se deve confundir recuperar a disponibilidade com garantir que a mesma geração seja executada uma única vez: essa garantia depende dos recursos documentados da API e do desenho da integração.

Este guia apresenta decisões que devem ser adaptadas ao fornecedor específico. A documentação de Kimi e ShareAI mencionada aqui serve de referência para as respectivas APIs, mas os trechos disponíveis não confirmam códigos de erro específicos, cabeçalhos de espera nem mecanismos de idempotência. Não transfira esses detalhes de um serviço para outro nem presuma que uma API os oferece só porque são comuns em outros serviços.

Classifique a falha antes de decidir

Não agrupe todas as respostas malsucedidas sob uma única regra automática. Separe, no mínimo, erros que indicam um problema de configuração ou validação, respostas relacionadas a limites de uso, tempos de espera esgotados e falhas de conexão. Essa classificação é um ponto de partida para investigar, não uma tabela universal de códigos: cada fornecedor define suas respostas e o que elas significam. Consulte a documentação atual da API e registre quais sinais justificam cada ação.

Um erro de validação, por exemplo, geralmente exige corrigir a solicitação, não enviá-la novamente sem alterações. Um limite de uso pode permitir que se continue mais tarde, mas é preciso seguir as instruções documentadas pelo serviço. Um timeout ou uma desconexão deixa em aberto outra pergunta: o serviço chegou a receber a solicitação? Se não for possível determinar isso, classifique o resultado como incerto, em vez de presumir que não houve processamento. Essa distinção é especialmente importante quando a operação pode gerar custos ou efeitos repetidos.

A decisão de fazer uma retentativa também deve levar em conta se a falha parece temporária, se faz sentido repetir a mesma solicitação e se ainda há orçamento de tempo e de tentativas. A fonte secundária sobre tentar novamente ou mudar de modelo recomenda limitar a retentativa a falhas transitórias, operações que possam ser repetidas com segurança e ao orçamento disponível. Esse é um critério geral de desenho, não uma definição oficial de erros de qualquer fornecedor.

Defina uma política explícita e finita

Uma política de retentativas deve especificar por escrito quais falhas podem levar a uma nova tentativa, quantas tentativas são permitidas, quanto pode durar o ciclo completo e o que o cliente deve fazer ao atingir o limite. Diferencie o envio inicial das retentativas: se configurar um máximo de tentativas totais, indique se esse número inclui a solicitação inicial. Essa precisão evita interpretações diferentes no código, na configuração e nas métricas.

O limite de tempo total — por vezes chamado de orçamento de tempo — deve abranger as pausas e as chamadas seguintes, e não apenas o tempo de conexão de uma tentativa. Se esse limite expirar, pare de programar novas repetições, mesmo que o número máximo de tentativas ainda não tenha sido atingido. Da mesma forma, atingir o máximo deve interromper a sequência mesmo que ainda haja tempo. Assim, evitam-se ciclos ilimitados e solicitações que continuam consumindo recursos muito depois de o chamador já não poder usar o resultado.

Não existe um número de tentativas nem uma duração apropriados para todas as APIs. Justifique esses parâmetros com base na latência tolerada pela aplicação, nas indicações do fornecedor, no custo potencial da operação e no comportamento medido durante falhas. O guia de ajuda da Kimi menciona uma estratégia de espera exponencial e o controle do número de solicitações; o trecho disponível não recomenda valores universais nem confirma que essa estratégia se aplique a todos os erros.

Quando a documentação de uma API indicar um sinal de espera, verifique o seu significado e alcance e siga as instruções estabelecidas pelo próprio fornecedor. Não invente o nome de um cabeçalho nem interprete um sinal de outro serviço como se fosse equivalente. Se não tiver sido verificado um sinal documentado, o cliente não deve fingir que consegue determinar, com base nele, o momento certo para retomar as tentativas.

Esperas progressivas e dispersão aleatória

Uma espera progressiva aumenta o intervalo entre tentativas consecutivas. Ela pode reduzir a pressão causada por chamadas repetidas e imediatas quando um serviço está sobrecarregado ou enfrenta uma interrupção. A documentação de solução de problemas da Kimi menciona a espera exponencial junto com o controle do número de solicitações. Essa referência confirma que esses conceitos aparecem na documentação da Kimi; não define uma configuração válida para outras APIs nem demonstra que uma espera específica seja adequada para todos os casos.

A dispersão aleatória, ou jitter, acrescenta variação às pausas para evitar que muitos clientes que falharam ao mesmo tempo voltem a chamar o serviço de forma sincronizada. É uma ferramenta de desenho possível, não uma obrigação universal. Avalie se ela é compatível com os sinais publicados pelo fornecedor e com o prazo máximo da operação. Se houver uma instrução de espera documentada, não a substitua por uma pausa aleatória que possa entrar em conflito com essa instrução.

Documente os parâmetros escolhidos e a justificativa de cada um: como as pausas aumentam, qual é o limite, que variação é aplicada e como a sequência é interrompida quando o orçamento expira. Meça o efeito com dados operacionais: número de tentativas por solicitação, sucessos após retentativas, duração total, erros finais e consumo associado, quando for possível medi-lo. Não transforme uma recomendação orientativa em um valor universal sem testar com o fornecedor e a carga reais.

Evite duplicidades: idempotência e resultados incertos

Idempotência é uma propriedade que permite repetir uma operação sem produzir efeitos adicionais, dentro das condições definidas pelo sistema. Em uma API, não basta encontrar o termo em uma página: descubra se o fornecedor oferece uma chave de idempotência ou um mecanismo equivalente, quais endpoints ou operações são cobertos, como a chave deve ser enviada, por quanto tempo é reconhecida e o que acontece se for reutilizada com parâmetros diferentes. Somente a documentação atual do fornecedor pode confirmar essas garantias.

As fontes disponíveis não verificam suporte a idempotência na Kimi nem na ShareAI. A página da ShareAI menciona expressamente que operações de escrita exigem cuidado, mas o trecho não confirma uma chave ou garantia específica. Portanto, não se deve afirmar que qualquer um desses fornecedores elimina duplicidades por padrão. Se a API não documentar um mecanismo aplicável, trate uma desconexão posterior ao envio como um resultado potencialmente incerto e consulte quais mecanismos de reconciliação o fornecedor oferece, se houver algum.

Diferencie consultar novamente uma operação já identificada de iniciar outra operação. Se a API documentar um identificador consultável, use-o somente dentro do alcance e do ciclo de vida descritos. Se não houver uma forma documentada de verificar o resultado, a integração terá de decidir entre parar, comunicar que o estado é incerto ou permitir uma repetição com um risco explícito. Não prometa execução exatamente uma vez sem uma garantia verificada que cubra o caso real.

Exemplo completo: a resposta se perde após o envio

Imagine que uma aplicação envia uma solicitação de geração. O cliente aguarda a resposta, mas a conexão é interrompida. Ele não sabe se o servidor recebeu a solicitação, se começou a processá-la ou se terminou. Em vez de repetir automaticamente, marque a tentativa como incerta e consulte a documentação daquela API: há uma chave de idempotência aplicável? Existe uma forma documentada de consultar o estado? Qual é a política do fornecedor para esse tipo de interrupção? A resposta determina a próxima ação.

Se houver um mecanismo documentado que cubra essa operação, a integração pode repetir a solicitação ou consultar o estado seguindo exatamente o seu alcance. Se não houver, não é possível deduzir, a partir do erro de transporte, que o serviço não processou a solicitação. A equipe deve aplicar a política de risco aprovada previamente: por exemplo, parar e mostrar um estado pendente de revisão ou permitir uma repetição, deixando claro que ela pode gerar outro consumo. A opção apropriada depende do impacto de duplicar a operação e dos mecanismos disponíveis; não há uma resposta universal.

Se o fornecedor der uma resposta definitiva, o ciclo termina conforme o significado documentado dessa resposta. Se houver sucesso, não se programam novas tentativas. Se uma falha temporária for confirmada e a repetição for segura, verifique novamente o limite, o orçamento e o tempo de espera. Se o orçamento expirar ou o máximo de tentativas for atingido, a sequência termina e o sistema registra o resultado final ou incerto. Em nenhum momento o contador deve ser reiniciado apenas porque outro processo passou a atender à solicitação.

Teste falhas realistas antes da implantação

Os testes devem verificar tanto a decisão de fazer uma retentativa quanto a decisão de parar. Simule uma falha que a configuração classifique como temporária e confirme que o cliente respeita o limite. Simule falhas persistentes e confirme que não há repetições indefinidas. Faça o orçamento de tempo expirar enquanto ainda houver tentativas disponíveis; depois, verifique se atingir o máximo também interrompe o ciclo, mesmo que ainda reste tempo.

Inclua uma resposta tardia e uma desconexão logo após o envio. São casos diferentes: a resposta tardia pode chegar quando o cliente já considera que o tempo de espera expirou, enquanto a desconexão após o envio deixa incerto o estado do processamento. Verifique se a aplicação evita duplicar uma operação por presumir que ambos os casos significam «o servidor não fez nada». Se o fornecedor oferecer um recurso de idempotência, os testes devem confirmar o seu alcance em um ambiente adequado e com base na documentação atual, em vez de simular uma garantia que o serviço não prometeu.

Acrescente casos de erro de validação e de limites de uso para confirmar que uma regra genérica não é aplicada a todas as respostas. Se o fornecedor publicar sinais de espera, teste a interpretação documentada. Por fim, verifique se os registros permitem reconstruir a ordem das tentativas sem guardar prompts, respostas ou dados sensíveis sem necessidade. Identificadores de correlação, tipo de resultado, tempos e número da tentativa costumam ser mais úteis para o diagnóstico do que copiar todo o conteúdo da solicitação.

Critérios para colocar a política em produção

Antes da implantação, registre qual documentação foi consultada, quando foi verificada e a que versão ou endpoint ela se aplica. Mantenha separadas as instruções do fornecedor e as decisões da aplicação: uma recomendação documentada não substitui a análise do risco de duplicidade, e uma política local não deve ser apresentada como garantia do serviço.

Analise os resultados depois da implantação. Um aumento no número de tentativas por chamada, de ciclos esgotados ou de resultados incertos pode indicar uma degradação, uma configuração agressiva demais ou uma mudança no comportamento do serviço. Trate o fallback — por exemplo, uma rota alternativa aprovada — como uma decisão diferente da retentativa: a fonte secundária sobre APIs de LLM recomenda mudar de rota somente para uma alternativa previamente aprovada. Verifique compatibilidade, qualidade, privacidade e custos antes de ativar um fallback; não o use para esconder que a chamada original pode ter sido processada.

Por fim, meça separadamente a recuperação técnica e a qualidade da resposta. O fato de uma chamada terminar com sucesso após várias tentativas não demonstra que o conteúdo gerado esteja correto ou seja adequado. Uma política robusta limita danos e esclarece os resultados; não substitui a avaliação da saída do modelo nem as decisões de segurança da aplicação.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.