Other Errors

Other Webhook Errors

Besides the most common errors (400, 403, 404, 408, and 500), some less frequent HTTP status codes may also appear in Webhook logs.

All of them follow the same behavior in the Asaas Webhook queue:

an event is considered successfully delivered only when the endpoint returns HTTP 200;
any other status code is treated as a failure;
retries are automatically performed according to the queue penalty policy;
after 15 consecutive failures, the queue is interrupted;
events remain stored for up to 14 days.

📘
Important
Regardless of the returned status code, Asaas does not interpret its meaning. For the system, any response other than HTTP 200 represents a failed attempt.

Less common status codes

301 - Moved Permanently

The URL configured for the webhook has been permanently moved to another address.

Example:

Before:

https://api.mysystem.com/webhook

After:

https://api.mysystem.com/api/webhook

Asaas does not automatically follow redirects.

How to fix

update the webhook URL;
avoid redirect responses.

307 - Temporary Redirect

The server responded with a temporary redirect.

Although the POST method is preserved, Asaas does not follow redirects.

How to fix

point directly to the final URL;
avoid proxies or rules that generate redirects.

405 - Method Not Allowed

The endpoint exists, but it does not accept POST requests.

Asaas Webhooks are always sent using:

POST

How to fix

Verify that the endpoint is configured to accept POST requests.

415 - Unsupported Media Type

The server does not accept the format sent by Asaas.

Webhooks use:

Content-Type: application/json

How to fix

Ensure that your application accepts JSON payloads.

429 - Too Many Requests

The endpoint rejected the request because too many requests were received.

This usually occurs because of:

rate limiting;
abuse protection mechanisms;
server limitations.

How to fix

increase request limits;
implement internal queues;
review rate limiting rules.

502 - Bad Gateway

A proxy, load balancer, or API Gateway failed while attempting to reach the origin server.

Examples:

Nginx;
Cloudflare;
AWS Load Balancer;
API Gateway.

How to fix

Check:

server availability;
proxy rules;
load balancer configurations.

503 - Service Unavailable

The server was temporarily unavailable.

The most common causes are:

maintenance activities;
overload;
temporary outages;
application restarts.

How to fix

Restore application availability and reactivate the queue.

504 - Gateway Timeout

The request was forwarded, but the server took too long to respond.

This is similar to the 408 error, but it usually occurs in an intermediate component.

How to fix

Check:

proxies;
load balancers;
internal APIs;
server response times.

Other status codes

The following status codes may also appear:

Code	Meaning
406	Response format not acceptable
409	Conflict during processing
412	Precondition failed
421	Request sent to the wrong server
451	Resource unavailable due to legal restrictions

How event retries work

Whenever a status code other than HTTP 200 is returned:

Event
↓
Failure
↓
Penalty
↓
Retry
↓
15 consecutive failures
↓
Queue interrupted

Events will continue to be stored for up to 14 days.

After that period, they will be permanently removed.

Best practices

always return HTTP 200 after receiving an event;
avoid redirects;
monitor application logs;
implement asynchronous processing;
use idempotency;
monitor CPU, memory, and database usage;
review rate limiting policies;
avoid critical external dependencies during webhook processing.

Encountered a different error?

If you encounter a status code not documented on this page, the behavior remains the same:

HTTP 200: success;
any other code: failure and retry.

In these situations, we recommend:

Reviewing application logs.
Checking Webhook logs.
Fixing the root cause.
Reactivating the queue if it has been interrupted.

Next steps

If you continue experiencing issues, we recommend consulting: