Outros Erros

Além de 400, 403, 404, 408, 500 e Connect Timed Out, outros códigos HTTP podem aparecer nos Logs de Webhooks.

Para a entrega, o comportamento é o mesmo: o Asaas considera o evento entregue somente quando o endpoint retorna HTTP 200. Outros códigos entram no fluxo de retentativas.

📘
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.

Como interpretar outros códigos HTTP

Código	Significado	O que verificar
`301 Moved Permanently`	A URL foi movida permanentemente.	URL configurada e possíveis redirecionamentos.
`307 Temporary Redirect`	O servidor redirecionou temporariamente a requisição.	Proxy, gateway e URL final do Webhook.
`405 Method Not Allowed`	A rota existe, mas não aceita `POST`.	Métodos HTTP permitidos pela rota.
`415 Unsupported Media Type`	O endpoint não aceita o formato recebido.	Suporte a `Content-Type: application/json`.
`429 Too Many Requests`	O endpoint aplicou limite de requisições.	Rate limit, proteção contra abuso e capacidade do servidor.
`502 Bad Gateway`	Um componente intermediário não conseguiu acessar o servidor de destino.	Proxy, gateway, balanceador e servidor de origem.
`503 Service Unavailable`	O serviço estava temporariamente indisponível.	Manutenção, sobrecarga ou disponibilidade da aplicação.
`504 Gateway Timeout`	Um componente intermediário não recebeu resposta dentro do tempo esperado.	Proxy, balanceador, APIs internas e tempo de resposta do servidor.

Redirecionamentos

301 - Moved Permanently

O 301 indica que a URL configurada no Webhook foi movida permanentemente.

Antes:

https://api.meusistema.com/webhook

Depois:

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

O Asaas não segue redirecionamentos automaticamente.

Atualize a configuração do Webhook para apontar diretamente para a URL final.

307 - Temporary Redirect

O 307 indica um redirecionamento temporário. Embora esse código preserve o método POST, o Asaas não acompanha o redirecionamento.

Verifique proxies, gateways e regras da aplicação e configure diretamente a URL que deve receber o evento.

Outros redirecionamentos HTTP, como 302 e 308, também não são seguidos automaticamente pelo Asaas.

Método e formato da requisição

405 - Method Not Allowed

O 405 indica que a rota existe, mas não aceita o método utilizado pelo Webhook.

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

POST

Configure a rota para receber requisições POST.

415 - Unsupported Media Type

O 415 indica que o servidor rejeitou o formato do conteúdo enviado.

Os Webhooks utilizam:

Content-Type: application/json

Configure o endpoint para receber e interpretar payloads JSON.

Limites e indisponibilidade

429 - Too Many Requests

O 429 indica que o próprio endpoint ou algum componente da infraestrutura limitou o volume de requisições.

Verifique:

regras de rate limiting;
proteção contra abuso;
limites do servidor, proxy ou gateway;
capacidade de processamento da aplicação.

Quando necessário, utilize filas internas para desacoplar o recebimento do evento do processamento da regra de negócio.

502 - Bad Gateway

O 502 normalmente indica que um proxy, balanceador ou API Gateway não conseguiu acessar o servidor responsável pelo processamento.

Verifique componentes como:

Nginx;
Cloudflare;
AWS Load Balancer;
API Gateway.

Confirme a disponibilidade do servidor de origem e as regras de encaminhamento.

503 - Service Unavailable

O 503 indica indisponibilidade temporária do serviço.

As causas mais comuns são:

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

Restabeleça o serviço. Se a fila do Webhook já tiver sido interrompida, reative-a somente após corrigir a indisponibilidade.

504 - Gateway Timeout

O 504 indica que um componente intermediário encaminhou a requisição, mas não recebeu resposta do servidor de destino dentro do tempo esperado.

Verifique:

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

Diferente do 408 - Read Timed Out, o 504 geralmente é retornado por um gateway ou proxy da própria infraestrutura.

Outros códigos

Também podem aparecer:

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

Use o código registrado nos Logs de Webhooks junto aos logs da aplicação, proxy ou gateway para identificar qual componente gerou a resposta.

O que acontece após uma falha

Sempre que o endpoint retorna um código diferente de HTTP 200:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Enviar evento"] --> B["Receber resposta diferente de HTTP 200"]
    B --> C["Aplicar penalização"]
    C --> D["Realizar nova tentativa"]
    D --> E["Atingir 15 falhas consecutivas"]
    E --> F["Interromper a fila"]

    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 validacao
    class F sucesso

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

Após 15 falhas consecutivas, a fila daquela configuração de Webhook é interrompida.

Os eventos pendentes permanecem armazenados por até 14 dias. Após esse período, os eventos mais antigos são removidos permanentemente.

Entenda a Penalização de filas.

Encontrou um código diferente?

Se o código não estiver documentado nesta página:

consulte os Logs de Webhooks;
localize a tentativa e o código retornado;
compare o horário com os logs da sua aplicação e infraestrutura;
identifique qual componente gerou a resposta;
corrija a causa antes de reativar uma fila interrompida.

Após a correção, confirme que as novas entregas retornam HTTP 200.

Próximos passos

Updated 1 day ago

Did this page help you?