DiscordStatus
Guias / Guides

Erro 500 (Internal Server Error)

O que fazer quando vejo este erro nos logs de Webhooks do Asaas?

O erro 500 Internal Server Error nos Logs de Webhooks indica que o Asaas conseguiu enviar a requisição ao endpoint, mas sua aplicação apresentou uma falha interna durante o processamento.

Nesse cenário, investigue os logs da aplicação, o tratamento do payload e as dependências utilizadas durante a requisição.

Principais causas

O erro pode ocorrer por:

  • exceções não tratadas;
  • falhas de conexão com banco de dados;
  • indisponibilidade de APIs externas;
  • problemas de autenticação com serviços terceiros;
  • consultas SQL com erro;
  • alto consumo de memória ou CPU;
  • desserialização incorreta do payload;
  • dependências indisponíveis;
  • timeout em chamadas internas;
  • falhas em filas ou workers.

Exemplo de falha

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas envia o Webhook"] --> B["Aplicação recebe o evento"]
    B --> C["Consultar banco de dados"]
    C --> D["Banco indisponível"]
    D --> E["Gerar exceção não tratada"]
    E --> F["Retornar HTTP 500"]
    F --> G["Evento entra em retentativa"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

O HTTP 500 confirma que a requisição chegou à aplicação. A investigação deve partir do erro gerado durante o processamento.

Como investigar

1. Consulte os Logs de Webhooks

Localize a tentativa com HTTP 500 em Logs de Webhooks.

Use o horário da tentativa e o payload enviado para localizar a mesma requisição nos logs da sua aplicação.

2. Consulte os logs da aplicação

Procure a exceção registrada no mesmo horário da tentativa.

Exemplos comuns:

NullReferenceException
Database connection timeout
SQL syntax error
Connection refused
Out of memory

A causa do 500 deve ser corrigida na aplicação ou na dependência que provocou a falha.

3. Verifique o tratamento do payload

Confirme se o parser aceita:

  • campos opcionais;
  • valores nulos;
  • atributos ainda não utilizados pela aplicação.
📘

Importante

A adição de novos atributos em Webhooks não representa quebra de contrato. Sua aplicação deve ser tolerante a campos adicionais.

Não rejeite o evento apenas porque o payload recebeu um novo atributo.

4. Verifique as dependências

Confirme a disponibilidade e o comportamento dos serviços utilizados durante o processamento:

  • banco de dados;
  • Redis;
  • RabbitMQ;
  • filas internas;
  • APIs externas;
  • serviços de autenticação;
  • serviços de e-mail.

Se uma dessas dependências puder atrasar ou interromper a requisição, mova o processamento para uma etapa assíncrona sempre que possível.

5. Reproduza o erro

Utilize Postman ou outra ferramenta HTTP para enviar à sua aplicação o mesmo payload registrado nos Logs de Webhooks.

Se o endpoint retornar 500 novamente, utilize os logs locais para identificar a etapa que gerou a exceção.

Corrija o fluxo de processamento

Evite executar toda a regra de negócio antes de confirmar o recebimento do evento.

O fluxo recomendado é:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Receber o evento"] --> B["Persistir o evento"]
    B --> C["Retornar HTTP 200"]
    C --> D["Processar em segundo plano"]
    D --> E["Executar regras de negócio"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D validacao
    class E sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Persista o id antes do processamento para suportar reenvios sem executar a mesma regra de negócio mais de uma vez.

Consulte como implementar idempotência em Webhooks.

O que acontece enquanto o erro persiste

O HTTP 500 não confirma a entrega do evento.

Enquanto as falhas continuarem:

  • o evento pode ser reenviado;
  • a configuração entra no mecanismo de penalização progressiva;
  • após 15 falhas consecutivas, a fila do Webhook é interrompida;
  • novos eventos continuam sendo armazenados;
  • eventos pendentes permanecem disponíveis por até 14 dias.

Entenda a Penalização de filas.

Como validar a correção

Após corrigir a aplicação:

  1. reproduza o payload que causava o erro e confirme que o endpoint não retorna mais 500;
  2. se a fila estiver interrompida, reative a configuração;
  3. gere ou aguarde um novo evento;
  4. consulte os Logs de Webhooks;
  5. confirme que as novas entregas retornam HTTP 200.

Após a recuperação, os eventos pendentes voltam a ser enviados conforme o tipo de envio configurado no Webhook.

Próximos passos

Updated 9 days ago

Did this page help you?