DiscordStatus
Guias / Guides

Error 400 (Bad Request)

The HTTP 400 Bad Request error indicates that the endpoint received the request sent by Asaas, but the application rejected the payload because it considered the content invalid or different from what was expected.

In most cases, the issue is not with the Webhook delivery itself, but with validations performed by the receiving application.

What happens when a 400 error occurs?

When the endpoint returns HTTP 400:

  • the event is not considered delivered;
  • Asaas starts retrying the delivery;
  • the queue enters progressive penalty mode;
  • after 15 consecutive failures, the queue is interrupted;
  • new events stop being delivered until the queue is reactivated.
🚧

Attention

A 400 error can completely interrupt synchronization between your application and Asaas if it is not fixed.

Common causes

The most frequent scenarios are:

  • expecting fields that do not exist in the payload;
  • validating optional fields as mandatory;
  • incorrect JSON deserialization;
  • rejecting newly added attributes;
  • overly restrictive validations;
  • attempting to convert values to incorrect types;
  • expecting only certain events;
  • using rigid structures that do not support payload evolution.

Common example

Imagine an application that always expects the following attribute:

{
  "payment": {
    "subscription": "sub_123"
  }
}

However, not all payments belong to a subscription.

In some events, the payload may be:

{
  "payment": {
    "subscription": null
  }
}

If the application treats this field as mandatory, it may return HTTP 400.

Another common example

An application may expect only specific attributes:

{
  "id": "evt_xxx",
  "event": "PAYMENT_RECEIVED"
}

However, Asaas may add new fields in the future:

{
  "id": "evt_xxx",
  "event": "PAYMENT_RECEIVED",
  "newAttribute": "value"
}

If the parser does not tolerate unknown attributes, the request may be rejected.

How to identify the issue

1. Check the Webhook logs

Review:

  • the payload sent;
  • the timestamp of the attempt;
  • the returned HTTP status code;
  • the number of retries.

See also:

How to view Webhook Logs

2. Compare the received payload

Review the documentation for the corresponding event and ensure that your application can handle:

  • optional attributes;
  • null values;
  • new attributes;
  • different event types.

Webhook behavior

Webhooks may be resent in case of failure.

For this reason, we recommend:

  • implementing idempotency;
  • not assuming that events are delivered only once;
  • processing only the fields you actually need;
  • ignoring unknown attributes.
📘

Important

Webhook payloads may evolve over time. Your system should be able to accept new attributes without throwing exceptions.

Best practices

✅ Accept optional fields.

✅ Ignore unknown attributes.

✅ Validate only the fields that are truly required.

✅ Implement application logs.

✅ Process Webhooks asynchronously.

✅ Implement idempotency.

✅ Return HTTP 200 after successfully receiving the event.

Troubleshooting flow

400 Error
↓
Check Webhook Logs
↓
Inspect the received payload
↓
Fix application validations
↓
Test again
↓
Return HTTP 200
↓
Queue resumes normal processing

Next steps

If you continue experiencing issues, we recommend consulting: