DiscordStatus
Guias / Guides

Outros Erros

Outros erros de Webhook

Além dos erros mais comuns (400, 403, 404, 408 e 500), alguns códigos HTTP menos frequentes também podem aparecer nos logs de Webhooks.

Todos eles seguem o mesmo comportamento da fila de Webhooks do Asaas:

  • o evento é considerado entregue com sucesso apenas quando o endpoint retorna HTTP 200;
  • qualquer outro código é tratado como falha;
  • novas tentativas são realizadas automaticamente conforme a política de penalização;
  • após 15 falhas consecutivas, a fila é interrompida;
  • eventos permanecem armazenados por até 14 dias.
📘

Importante

Independentemente do código retornado, o Asaas não interpreta o significado da resposta. Para o sistema, qualquer código diferente de 200 representa uma tentativa malsucedida.

Códigos menos frequentes

301 - Moved Permanently

A URL configurada no webhook foi movida permanentemente para outro endereço.

Exemplo:

Antes:

https://api.meusistema.com/webhook

Depois:

https://api.meusistema.com/api/webhook

O Asaas não segue redirecionamentos automaticamente.

Como resolver

  • atualizar a URL do webhook;
  • evitar respostas de redirecionamento.

307 - Temporary Redirect

O servidor respondeu com redirecionamento temporário.

Embora o método POST seja preservado, o Asaas não acompanha redirecionamentos.

Como resolver

  • apontar diretamente para a URL final;
  • evitar proxies ou regras que gerem redirecionamentos.

405 - Method Not Allowed

O endpoint existe, mas não aceita requisições POST.

Os Webhooks do Asaas são enviados através do método:

POST

Como resolver

Verifique se o endpoint foi configurado para aceitar POST.

415 - Unsupported Media Type

O servidor não aceita o formato enviado pelo Asaas.

Os Webhooks utilizam:

Content-Type: application/json

Como resolver

Certifique-se de que sua aplicação aceita payloads JSON.

429 - Too Many Requests

O endpoint rejeitou a requisição por excesso de chamadas.

Isso normalmente ocorre devido a:

  • rate limit;
  • proteção contra abuso;
  • limitação do servidor.

Como resolver

  • aumentar os limites de requisições;
  • implementar filas internas;
  • revisar regras de rate limiting.

502 - Bad Gateway

Um proxy, balanceador ou API Gateway falhou ao acessar o servidor principal.

Exemplos:

  • Nginx;
  • Cloudflare;
  • AWS Load Balancer;
  • API Gateway.

Como resolver

Verifique:

  • disponibilidade do servidor;
  • regras do proxy;
  • balanceadores de carga.

503 - Service Unavailable

O servidor estava temporariamente indisponível.

As causas mais comuns são:

  • manutenção;
  • sobrecarga;
  • indisponibilidade temporária;
  • reinicialização da aplicação.

Como resolver

Restabeleça a disponibilidade da aplicação e reative a fila.

504 - Gateway Timeout

A requisição foi encaminhada, mas o servidor demorou demais para responder.

É semelhante ao erro 408, porém geralmente ocorre em algum componente intermediário.

Como resolver

Verifique:

  • proxies;
  • balanceadores;
  • APIs internas;
  • tempo de resposta do servidor.

Outros códigos

Também podem aparecer:

CódigoSignificado
406Formato de resposta não aceito
409Conflito durante o processamento
412Pré-condição não atendida
421Requisição enviada para servidor incorreto
451Recurso indisponível por restrições legais

Como funciona o reenvio dos eventos

Sempre que um código diferente de HTTP 200 é retornado:

Evento
↓
Falha
↓
Penalização
↓
Nova tentativa
↓
15 falhas consecutivas
↓
Fila interrompida

Os eventos continuarão sendo armazenados por até 14 dias.

Após esse período, serão removidos permanentemente.

Boas práticas

  • responder sempre com HTTP 200 após receber o evento;
  • evitar redirecionamentos;
  • monitorar logs da aplicação;
  • implementar processamento assíncrono;
  • utilizar idempotência;
  • monitorar CPU, memória e banco de dados;
  • revisar limites de rate limiting;
  • evitar dependências externas críticas no recebimento do webhook.

Encontrou um erro diferente?

Caso apareça algum código não documentado nesta página, a lógica de funcionamento continua sendo a mesma:

  • HTTP 200: sucesso;
  • qualquer outro código: falha e retentativa.

Nesses casos, é recomendado:

  1. Consultar os logs da aplicação.
  2. Verificar os logs do webhook.
  3. Corrigir a causa do erro.
  4. Reativar a fila caso ela tenha sido interrompida.

Conteúdos relacionados