Ao receber um 429 na AIMLAPI, verifique primeiro se a aplicação e o SDK estão ambos fazendo novas tentativas

A documentação oficial do SDK Python da AIMLAPI lista duas novas tentativas automáticas por padrão. Se a tarefa externa também tentar novamente, o número de tentativas se acumula; antes do lançamento, centralize essa responsabilidade e trate separadamente erros de parâmetros, saldo insuficiente e limites de solicitações.

Fonte: github.com
November 11, 2026
4 min

Conectar vários modelos à mesma interface pode reduzir o código de integração, mas não faz com que tenham as mesmas restrições de parâmetros ou o mesmo comportamento em caso de falha. Para equipes que preparam a integração da AIMLAPI em funcionalidades para clientes, vale verificar primeiro o que o sistema fará quando ocorrer uma falha: quantas chamadas uma ação do usuário realmente gera, quando elas param e quem assume o tratamento da falha. Este artigo analisa esses limites com base nas explicações oficiais de erros, na documentação de chaves e no README do SDK Python. Não foram executados testes de carga.

Duas camadas de novas tentativas amplificam uma falha

O README oficial do SDK Python informa que erros de conexão e erros 408, 409, 429 e de código 500 ou superior recebem, por padrão, duas novas tentativas automáticas, que podem ser ajustadas ou desativadas com max_retries. Essas “duas novas tentativas” são adicionais à chamada inicial. Suponha que a camada externa da aplicação também repita toda a operação duas vezes após uma falha e que cada chamada ao SDK encontre erros que permitem nova tentativa e esgote as tentativas adicionais padrão: uma tarefa de negócio pode gerar até 3 × 3 = 9 tentativas. Esse é um exemplo de limite superior calculado sob hipóteses explícitas, não tráfego medido na plataforma, e não significa que as nove tentativas serão cobradas.

A central de ajuda explica o 429 como um limite de taxa ou de concorrência e recomenda reduzir a taxa de solicitações, tentar novamente com espera progressiva ou usar uma fila. Se a camada externa reenviar imediatamente sempre que detectar uma falha, poderá agravar a mesma limitação. Recomenda-se que uma única camada gerencie o orçamento de novas tentativas, registre o motivo e a contagem de cada tentativa e estabeleça condições claras de parada para a tarefa de negócio. Não deixe que o navegador, a fila de tarefas e o SDK decidam independentemente reenviar sem limite.

O tempo de espera também precisa ser analisado separadamente: o README do SDK lista um tempo limite padrão de 10 minutos por solicitação, configurável por timeout. Esse padrão não pode ser tratado diretamente como uma promessa de tempo de espera ao cliente. Recursos interativos precisam de seu próprio orçamento total de espera e de uma resposta clara quando ele se esgotar; tarefas em segundo plano devem permitir que o usuário consulte o estado real: em processamento, falha ou concluída.

Alguns erros não são resolvidos com novas tentativas

A tabela oficial de erros lista um caso de 400: o modelo escolhido não aceita o papel system em messages. Nessa situação, ajuste a solicitação conforme o schema desse modelo, em vez de presumir que uma interface unificada significa que todos os modelos aceitam os mesmos parâmetros. Antes de mudar para um modelo de reserva, verifique também se ele aceita a estrutura de mensagens existente e os requisitos da tarefa; caso contrário, uma degradação do serviço se transformará em outro erro de solicitação.

A tabela também classifica como 403 o esgotamento do saldo ou da cota do plano. A abordagem é diferente da usada para o 429: o primeiro exige verificar a cota da conta e o orçamento; o segundo, controlar o ritmo das chamadas. Recomenda-se classificá-los separadamente no monitoramento e manter identificadores de solicitação e informações de erro sem conteúdo sensível. Não classifique toda resposta sem sucesso como “modelo ocupado”, nem deixe que uma recarga automática substitua o diagnóstico da falha.

Controlar gastos não substitui controlar o tráfego

A documentação de chaves permite definir um limite de gastos para cada API key, impedindo que ela gere novas despesas ao atingir esse limite. É possível escolher períodos de redefinição diários, semanais ou mensais, entre outros, e a redefinição segue o horário UTC. A documentação também permite restringir os endpoints que a chave pode chamar. Essas medidas ajudam a separar os usos dos projetos e os limites de gastos, mas um teto de gastos não é uma configuração de taxa de chamadas nem prova que não haverá tentativas repetidas.

Antes da integração, a equipe pode conferir os registros com um cenário de falha controlado: há distinção entre 400, 403 e 429? O número real de tentativas respeita o orçamento? A espera total atende aos requisitos do produto? O modelo de reserva passou por uma verificação de compatibilidade? Se essas questões ainda não tiverem responsáveis, a conveniência da interface unificada não basta para sustentar um compromisso de lançamento. Conclua primeiro essa validação e só então amplie o volume de chamadas.

Nota sobre o conteúdo:Este artigo foi elaborado com base em informações públicas e serve como referência para a escolha de ferramentas. Os recursos, os preços e as políticas relacionadas podem mudar a qualquer momento; consulte as informações oficiais mais recentes.

Fonte original:github.com