Other Errors

In addition to 400, 403, 404, 408, 500, and Connect Timed Out, other HTTP codes may appear in the Webhook Logs.

For delivery, the behavior is the same: Asaas only considers the event delivered when the endpoint returns HTTP 200. Other codes enter the retry flow.

How to interpret other HTTP codes

Redirects

301 - Moved Permanently

301 indicates that the URL configured in the Webhook was moved permanently.

Before:

https://api.meusistema.com/webhook

After:

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

Asaas does not follow redirects automatically.

Update the Webhook configuration to point directly to the final URL.

307 - Temporary Redirect

307 indicates a temporary redirect. Although this code preserves the POST method, Asaas does not follow the redirect.

Check proxies, gateways, and application rules, and configure the URL that should receive the event directly.

Other HTTP redirects, such as 302 and 308, are not followed automatically by Asaas either.

Request method and format

405 - Method Not Allowed

405 indicates that the route exists but does not accept the method used by the Webhook.

Asaas Webhooks are sent using the method:

POST

Configure the route to receive POST requests.

415 - Unsupported Media Type

415 indicates that the server rejected the format of the content sent.

Webhooks use:

Content-Type: application/json

Configure the endpoint to receive and parse JSON payloads.

Limits and unavailability

429 - Too Many Requests

429 indicates that the endpoint itself or some infrastructure component limited the volume of requests.

Check:

• rate limiting rules;
• abuse protection;
• server, proxy, or gateway limits;
• the application's processing capacity.

When necessary, use internal queues to decouple receiving the event from processing the business rule.

502 - Bad Gateway

502 usually indicates that a proxy, load balancer, or API Gateway could not reach the server responsible for processing.

Check components such as:

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

Confirm the availability of the origin server and the forwarding rules.

503 - Service Unavailable

503 indicates temporary unavailability of the service.

The most common causes are:

• maintenance;
• overload;
• temporary unavailability;
• application restart.

Restore the service. If the Webhook queue has already been interrupted, only reactivate it after fixing the unavailability.

504 - Gateway Timeout

504 indicates that an intermediate component forwarded the request but did not receive a response from the destination server within the expected time.

Check:

• proxies;
• load balancers;
• internal APIs;
• server response time.

Unlike 408 - Read Timed Out, 504 is usually returned by a gateway or proxy in your own infrastructure.

Other codes

The following may also appear:

Use the code recorded in the Webhook Logs together with the application, proxy, or gateway logs to identify which component generated the response.

What happens after a failure

Whenever the endpoint returns a code other than HTTP 200:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Send event"] --> B["Receive response other than HTTP 200"]
    B --> C["Apply penalty"]
    C --> D["Make a new attempt"]
    D --> E["Reach 15 consecutive failures"]
    E --> F["Interrupt the queue"]

    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

After 15 consecutive failures, the queue for that Webhook configuration is interrupted.

Pending events remain stored for up to 14 days. After this period, the oldest events are permanently removed.

Understand Queue penalty.

Found a different code?

If the code is not documented on this page:

1. check the Webhook Logs;
2. find the attempt and the code returned;
3. compare the time with your application and infrastructure logs;
4. identify which component generated the response;
5. fix the cause before reactivating an interrupted queue.

After the fix, confirm that new deliveries return HTTP 200.

Next steps

• Check the Webhook Logs
• Understand Queue penalty
• Understand the Paused queue behavior
• Reactivate an interrupted queue
• Review how events are received
• Implement idempotency in Webhooks