Aumentando o Timeout do Lambda: Como Configurar e Qual é o Limite Máximo

Sua função Lambda encerra abruptamente após 3 segundos, mas o processamento real precisa de 10 segundos — esse é um dos erros mais comuns em produção com Lambda, e a causa quase sempre é o timeout padrão que nunca foi ajustado. Aumentar o timeout do Lambda é simples, mas entender os limites, o impacto no custo e os sinais de diagnóstico corretos evita retrabalho.

TL;DR — Timeout do Lambda em 30 Segundos

Ponto	Detalhe
Timeout padrão	3 segundos
Timeout máximo	900 segundos (15 minutos)
Onde configurar	Console AWS, AWS CLI, IaC (SAM/CDK/Terraform)
Erro no log	`Task timed out after X.XX seconds`
Impacto no custo	Cobrança por duração — timeout maior não aumenta custo se a função terminar antes

Como o Timeout do Lambda Funciona

O Lambda executa sua função dentro de um ambiente de execução gerenciado. Quando você invoca uma função, o serviço inicia um timer no momento em que o handler começa a rodar. Se esse timer atingir o valor configurado antes de a função retornar, o Lambda força o encerramento do processo — sem exceção capturável, sem callback, sem cleanup garantido. O ambiente é descartado.

O timeout é um atributo da configuração da função, não da invocação. Isso significa que cada versão publicada carrega seu próprio valor de timeout, e aliases apontam para versões específicas com seus respectivos limites.

graph TD A["Invocação recebida"] --> B["Ambiente de execução alocado"] B --> C["Handler chamado
Timer inicia"] C --> D{"Função retorna
antes do timeout?"} D -- "Sim" --> E["Execução bem-sucedida
Timer cancelado"] D -- "Não" --> F["Timeout atingido
Processo encerrado à força"] F --> G["Log: Task timed out
after X.XX seconds"]

Invocação recebida: o Lambda aloca ou reutiliza um ambiente de execução.
Timer inicia: a contagem começa quando o handler é chamado.
Função retorna antes do limite: execução bem-sucedida, timer cancelado.
Timer expira: o Lambda injeta um sinal de encerramento forçado — o processo é morto e o log registra Task timed out after X.XX seconds.

Identificando o Problema: O Log que Confirma Timeout

Antes de alterar qualquer configuração, confirme que o problema é realmente timeout e não uma exceção não tratada. Os dois se parecem no console, mas têm causas diferentes.

Verifique os logs no CloudWatch Logs do grupo /aws/lambda/<nome-da-função>. Uma execução encerrada por timeout sempre termina com esta linha:

REPORT RequestId: <id>  Duration: 3000.00 ms  Billed Duration: 3000 ms  ...
...
Task timed out after 3.00 seconds

Se a linha Task timed out está presente, o problema é timeout. Se você vê um stack trace de exceção antes do REPORT, o problema é outro — aumentar o timeout não vai resolver.

Via CLI, você pode buscar esse padrão diretamente:

aws logs filter-log-events \
  --log-group-name '/aws/lambda/minha-funcao' \
  --filter-pattern 'Task timed out' \
  --region us-east-1

Aumentando o Timeout do Lambda — 3 Formas

Opção 1: Console AWS (Mais Rápido para Testes)

Acesse o console do Lambda, abra sua função, vá em Configuração → Configuração geral → Editar. O campo 'Timeout' aceita valores em minutos e segundos. Ajuste para o valor necessário e salve. A alteração é aplicada imediatamente para novas invocações.

Opção 2: AWS CLI (Recomendado para Automação)

Este é o caminho correto quando você precisa ajustar timeout em múltiplas funções ou integrar em pipelines de deploy.

aws lambda update-function-configuration \
  --function-name minha-funcao \
  --timeout 30 \
  --region us-east-1

O parâmetro --timeout recebe o valor em segundos (inteiro). Para confirmar que a alteração foi aplicada:

aws lambda get-function-configuration \
  --function-name minha-funcao \
  --region us-east-1 \
  --query 'Timeout'

Opção 3: AWS SAM (IaC)

Se sua função é gerenciada via SAM, altere o template e faça deploy. Nunca edite manualmente uma função gerenciada por IaC — o próximo deploy vai sobrescrever sua alteração.

Resources:
  MinhaFuncao:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: python3.12
      Timeout: 30

sam deploy \
  --template-file template.yaml \
  --stack-name minha-stack \
  --capabilities CAPABILITY_IAM \
  --region us-east-1

Permissões IAM Necessárias para Alterar o Timeout

Para executar update-function-configuration, a identidade precisa da permissão lambda:UpdateFunctionConfiguration na função alvo. Abaixo, uma política de escopo mínimo:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "lambda:UpdateFunctionConfiguration",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:minha-funcao"
    },
    {
      "Effect": "Allow",
      "Action": "lambda:GetFunctionConfiguration",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:minha-funcao"
    }
  ]
}

Limite Máximo e o que Fazer Quando 15 Minutos Não São Suficientes

O Lambda aceita timeout de 1 segundo até 900 segundos (15 minutos). Esse é um limite de serviço — não é configurável por conta ou região.

Se sua tarefa genuinamente ultrapassa 15 minutos, o Lambda não é o serviço correto para essa carga de trabalho. As alternativas documentadas pela AWS para workloads de longa duração incluem:

AWS Step Functions: orquestra múltiplas invocações Lambda em sequência, contornando o limite por função.
AWS Fargate / ECS: containers sem limite de tempo de execução imposto pelo serviço.
AWS Batch: para processamento em lote com duração variável.

graph TD START["Tarefa precisa de mais
de 3 segundos"] --> Q1{"Termina em
menos de 15 min?"} Q1 -- "Sim" --> Q2{"Pode dividir
em etapas?"} Q1 -- "Não" --> C["Fargate / ECS / Batch"] Q2 -- "Não necessário" --> A["Aumentar timeout
na função Lambda"] Q2 -- "Sim, faz sentido" --> B["Step Functions +
múltiplas funções Lambda"]

Se a tarefa termina em menos de 15 minutos: aumente o timeout diretamente na configuração da função Lambda.
Se a tarefa pode ser dividida em etapas menores: use Step Functions para encadear execuções Lambda.
Se a tarefa é intrinsecamente longa e indivisível: migre para Fargate ou Batch.

Diagnóstico Avançado: Quando o Timeout Aumentado Ainda Falha

Aqui está um padrão que aparece com frequência em produção: você aumenta o timeout de 3 para 30 segundos, faz o deploy, e a função continua falhando — mas agora o log mostra timeout em 29 segundos em vez de 3. O timeout foi aplicado, mas o problema real nunca era o timeout da função.

Sintoma: função falha consistentemente próximo ao novo limite de timeout, independente do valor configurado.

Diagnóstico errado: 'preciso aumentar mais o timeout'.

Causa real: a função está aguardando uma conexão externa (banco de dados, API, serviço downstream) que nunca responde. O timeout do Lambda está correto — o problema está no timeout da conexão dentro do código, ou na disponibilidade do serviço externo.

Verifique se há chamadas de rede sem timeout explícito no código. Em Python, por exemplo, requests.get(url) sem o parâmetro timeout aguarda indefinidamente até o Lambda encerrar a execução. A função vai sempre consumir todo o timeout configurado.

Verifique também se a função está em uma VPC e se as rotas para o serviço externo estão configuradas corretamente — uma função em VPC sem NAT Gateway ou VPC Endpoint não consegue alcançar endpoints públicos, e a conexão trava silenciosamente até o timeout.

aws lambda get-function-configuration \
  --function-name minha-funcao \
  --region us-east-1 \
  --query 'VpcConfig'

Se VpcId estiver preenchido, confirme a conectividade de saída antes de ajustar qualquer timeout.

Impacto no Custo ao Aumentar o Timeout do Lambda

O Lambda cobra por duração real de execução, não pelo timeout configurado. Configurar timeout de 900 segundos em uma função que termina em 10 segundos não altera o custo — você paga pelos 10 segundos executados.

O risco real é diferente: um timeout alto em uma função com bug pode deixar execuções travadas consumindo duração máxima repetidamente, especialmente com concorrência alta. Configure o timeout no valor mais próximo do tempo de execução esperado mais uma margem razoável — não no máximo absoluto.

Timeout é como um disjuntor: você não configura para o pior cenário teórico, mas para o pior cenário operacional aceitável. Um disjuntor calibrado muito alto não protege nada.

Próximos Passos e Recursos Oficiais

Após ajustar o timeout do Lambda, monitore a métrica Duration no CloudWatch para validar que as execuções estão terminando dentro do novo limite com margem adequada. Configure um alarme em Duration próximo ao timeout configurado para detectar degradação antes que vire erro.

Glossário

Termo	Definição
Timeout	Tempo máximo que o Lambda permite para uma função completar sua execução antes de forçar o encerramento.
Ambiente de execução	Ambiente isolado (microVM) onde o código da função Lambda roda. Pode ser reutilizado entre invocações (warm start).
Duração faturada	Tempo de execução arredondado para cima em incrementos de 1ms, usado para cálculo de custo.
Concorrência	Número de instâncias da função executando simultaneamente. Afeta o custo total quando combinado com timeout alto.
VPC Endpoint	Conexão privada entre sua VPC e serviços AWS, sem tráfego pela internet pública.

Pesquisar este blog

SW BBANG P