Common errors

Use this page to diagnose failures in checkout, charge creation, subscriptions, and Webhook synchronization.

Always start with the Asaas Plugin's Debug Log. It records the response received from the API and helps identify the cause before changing settings.

Enable the Debug Log

Go to:

WooCommerce > Settings > Payments

Select an Asaas payment method and enable Enable Log in the Debug Log section.

Save the changes and reproduce the problem.

Then, go to:

WooCommerce > Status > Logs

The Asaas Plugin logs have the prefix asaas followed by the payment method:

• credit-card: Credit Card;
• ticket: Bank Slip;
• pix: Pix.

Open the most recent record related to the error.

API communication failures may show an EMERGENCY entry along with the code returned by Asaas.

Use the code and message found in the log to follow the diagnosis below.

WooCommerce problems

The plugin stopped working after an update

Before downgrading:

1. confirm that WordPress, WooCommerce, and the plugin dependencies are up to date;
2. check the Debug Log;
3. reproduce the problem on the latest version;
4. look for incompatibilities with other plugins.

If a downgrade is necessary for diagnosis, go to the Asaas Plugin page on WordPress, click Advanced View, and use the previous versions area.

Error "There was an error processing your order. Please contact us."

This error usually indicates a failure during charge creation.

After reproducing the problem, check the Debug Log and locate the EMERGENCY entry.

Use the returned HTTP code and message to identify the cause.

Error "There are no payment methods available"

This scenario can occur when the checkout page uses the WooCommerce block structure and the version or configuration used is not compatible with the Asaas Plugin.

As an alternative, configure the checkout page with the classic template using:

[woocommerce_checkout]

After the change, make a new test purchase.

Error 401

HTTP 401 indicates that the API Key was not sent correctly or is not valid.

Check:

• that the API Key is active;
• that it was copied in full;
• that the key belongs to the selected environment;
• that Sandbox and Production were not mixed in the same configuration.

After fixing the credential, save and create a new order.

If necessary, review Initial settings.

Error 403

HTTP 403 indicates that the request was not authorized.

In the API flow, one possible cause is the country of origin of the IP used by the server. There may also be security restrictions configured for the account.

Check the origin of the requests and the restrictions applied before running a new test.

Error 404 after switching account or environment

This scenario can occur when the same WooCommerce installation is used with different Asaas accounts or after switching between Sandbox and Production.

The plugin may keep in WordPress the identifier of the customer previously created in Asaas. Since customers are independent between accounts and environments, this ID may not exist in the new account.

Before removing any data, query the affected records:

SELECT user_id, meta_key, meta_value
FROM wp_usermeta
WHERE meta_value LIKE '%cus_000%';

Confirm that the records found belong to the customers that need to be recreated in the new environment.

After validation, the currently documented procedure to remove the stored identifiers is:

DELETE FROM wp_usermeta
WHERE meta_value LIKE '%cus_000%';

After the removal, make a new purchase so that the customer is created in the configured environment.

The subscription only creates the order

Current versions of the Asaas Plugin declare support for High-Performance Order Storage (HPOS).

If only the order is created:

1. update the Asaas Plugin and WooCommerce Subscriptions;
2. run a new test;
3. check the logs if the subscription is still not created.

As a compatibility alternative, go to:

WooCommerce > Settings > Advanced > Features

Then:

• enable WordPress posts storage (legacy); or
• click Enable compatibility mode, synchronize the subscriptions, and try again.

Also see WooCommerce Subscriptions.

The order is not marked as completed

In WooCommerce, orders for physical products may require manual completion.

For WooCommerce to treat the product as eligible for automatic completion, configure it as:

• Virtual;
• Downloadable.

Webhook problems

The payment was confirmed, but the order was not updated

Check the queue status in:

WooCommerce > Status > Meio de Pagamentos Asaas

If the queue is interrupted, the Re-enable webhook queue option will be displayed.

Before reactivating:

1. check the Webhook Logs;
2. identify the HTTP code or communication error;
3. fix the cause;
4. go back to WooCommerce and click Re-enable webhook queue.

After recovery, the status should be updated and the button will become unavailable.

See WooCommerce Webhooks to monitor the health of the synchronization.

Error 403 on Webhooks

An HTTP 403 on Webhooks usually indicates that the request reached the store's infrastructure but was blocked before processing.

Check:

• Firewall;
• WAF or Cloudflare;
• IP restriction rules;
• header validations;
• hosting security mechanisms.

If there is an allowlist, check the official Asaas IPs.

Error 500 on Webhooks

HTTP 500 indicates an internal failure on the server receiving the Webhook.

Check:

• the Debug Log and the server logs;
• that the Asaas Plugin is up to date;
• that the server and its dependencies are available;
• whether there are exceptions during processing;
• whether there are duplicate Webhooks configured for the same store.

Fix the failure before reactivating the queue.

See the error 500 guide.

Error 408 on Webhooks

408 Read Timed Out indicates that Asaas established the connection but did not receive a response within 10 seconds.

Avoid lengthy processing before responding to the Webhook.

When possible:

1. receive and persist the event;
2. respond with success;
3. process longer tasks asynchronously.

After fixing the timeout, reactivate the queue.

See the error 408 guide.

Incompatibility with other plugins

If the Asaas Plugin shows behaviors such as:

• QR Code not displayed;
• customer created without the charge being generated;
• unexpected checkout failures;
• Webhook processing failures;

check whether another plugin is modifying the checkout or order processing.

Checkout customization plugins are a common point of conflict.

To investigate:

1. keep the Debug Log enabled;
2. reproduce the problem;
3. temporarily disable checkout-related plugins in a test environment;
4. repeat the operation to identify the conflict.

Next steps

• Monitor the WooCommerce Webhooks
• See the Webhook Logs
• Review the initial settings
• See the WooCommerce FAQ