> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/integrations/order-orchestration/troubleshooting-order-processing.md).

# Troubleshooting Order Processing

When an order is processed through the Order Orchestration Framework, every step is recorded in a **Process Event**. This page explains how to find errors, inspect callouts, view logs, and resolve common issues.

## Process Events

Process events are created for every order execution. They contain:

* Callouts made to other systems, including endpoint and time to execute
* Payload for each individual callout
* Errors from third-party systems
* Detailed logs on the order processing

### How to Find Process Events

#### Through Events

1. Go to **Events** in Limio.
2. Click on **Process Events** in the upper right corner.
3. Search by **Created Date** (you will need to have "Filter by Created" activated). You can also filter to show only process events with errors.

#### Through Subscriptions

If you are looking for a specific customer:

1. Go to **Subscriptions** and search for the customer.
2. Find the **Event** table and click on the event you are interested in.
3. Click on the **Process Events** link.

## Inspecting Callouts

Limio allows you to view each callout made to a third-party system during order processing. The callout table includes a timestamp, the specific endpoint called, and the time taken to perform the callout.

### Viewing Callout Details

Click on any individual callout to view the payload sent to the endpoint.

### Inspecting Zuora Callouts

When looking at callouts to Zuora, the most important callout is typically the POST to `https://rest.apisandbox.zuora.com/v1/orders` (or the production equivalent). By inspecting this callout, you can see the exact payload sent for a New Order, Cancellation, Add/Remove Product, Update Product, etc.

1. In the process event, find the **Callout** table.
2. Click on **Details** for the callout you want to inspect.
3. You'll see a JSON view of the callout including errors, request timings, and order details.

Learn more about how Limio processes different customer events in Zuora: [How Limio Events Update Zuora](https://docs.limio.com/integrations/keeping-zuora-and-limio-in-sync/how-limio-events-updates-zuora-for-commerce.md).

## Viewing Processing Logs

To see a step-by-step breakdown of what happened during order processing, scroll to the bottom of the process event page and look for the **Message** header section. This shows all processing logs with timestamps.

## Errors from Third-Party Systems

If a third-party system fails, the process event includes the top-level error message and detailed logs.

For example, Zuora might reject an order because of a missing product code — this means the Limio Offer wasn't properly configured.

### Understanding Zuora Errors

When a Zuora callout fails:

1. Select the `v1/orders` POST request in the callouts table.
2. Expand the response object and copy the error `code` value.
3. Look up the code in the [Zuora Error Code Documentation](https://developer.zuora.com/docs/guides/error-codes/).

### Payment gateway errors (`gatewayResponse`)

When the payment gateway declines or fails a payment, the error message of the Zuora plugin can contain a `gatewayResponse` object:

```json
{ "gatewayResponse": { "code": "203", "message": "REJECT" } }
```

The `code` and the `message` come from your payment gateway, through Zuora. Limio does not change them. To find the cause, look up the code in the documentation of the payment gateway that Zuora used for the payment.

From release 118.0.36 (and 116.0.63 on the 116 line), if you submit the order with the [Submit Order API](https://docs.limio.com/api/orders-api/orders) and management credentials, the response gives the same data in a `payment` object:

| Field            | Content                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `processorError` | The `code` and the `message` from the gateway, with no change.                                                 |
| `reason`         | A reason that Limio derives from the gateway message. A message of `ERROR` gives `processing_error`.           |
| `retry`          | `payment_method`: ask the customer for a different payment method. `none`: do not submit the same order again. |

A gateway message of `ERROR` always gives `retry: none`.

### The message "Order could not be processed"

`Order could not be processed` is the message that Limio returns to the checkout when a critical plugin fails. Limio returns the same message when processing stops before the plugins run. The message does not name the cause. To find the cause, open the process event of the order and read the plugin error.

## What Limio Does After a Failed Order

When a critical plugin fails, Limio stops the sequence. The plugins that come after it do not run. Limio then does these steps:

* It sets the status of the process event to `error` and records the error message of each plugin that failed.
* It marks the event as an event with an error.
* It sends the [Error webhook](https://docs.limio.com/integrations/order-orchestration/webhooks-and-notifications.md#error-webhook).

Limio does not start the sequence again after a plugin failure. If Limio cannot start the processing when the order is submitted, it puts the event in a queue and processes it later.

Limio does not undo the work that it did before the failure:

* Limio creates the Limio order record before the plugins run. For a new order, it also creates the Limio customer and the Limio subscription. The subscription keeps the status **Initial**. See [Subscription Statuses in Limio and Zuora](https://docs.limio.com/integrations/keeping-zuora-and-limio-in-sync/sync-between-limio-subscriptions-and-zuora-subscriptions/subscription-statuses-in-limio-and-relation-with-zuora.md).
* Each plugin that completed before the failure keeps its result. For example, if the Salesforce V3 plugin ran before the Zuora plugin, the Salesforce Account stays in Salesforce.

Before a customer or an agent submits the order again, find out how far the first order went:

1. Open the process event and find the plugin that failed.
2. If the Zuora plugin ran, search Zuora for the order. For a new order, the Zuora order number is the Limio order reference.

A new submission of the order is a new event. Limio processes it from the first step, and the Zuora plugin sends the order to Zuora again. Limio does not remove the first order from Zuora.

{% hint style="info" %}
A new order that has an `external_id` has one safeguard. If the latest new order with the same `external_id` does not have the status `error`, Limio returns that order and does not create a second one. If it has the status `error`, Limio accepts the new submission.
{% endhint %}

### Process and Force Process

The page of an event in the Limio app has two buttons. You must have write permission on events to see them.

* **Process** runs the sequence for an event that Limio has not processed. If the event has a process event, Limio stops with the message `Event <id> has already been processed, see <process id> record`. A failed event has a process event, so **Process** does not run it again.
* **Force Process** runs the sequence again for the same event. Limio creates a new process event and a new Limio order record, and runs every plugin from the first step. The plugins that completed in the first run, run again.

{% hint style="warning" %}
For a new order, **Force Process** creates new Limio subscriptions. The subscriptions from the failed run stay, with the status **Initial**. The Zuora plugin sends the order to Zuora again. Do the checks above before you use it.
{% endhint %}

## Common Salesforce V3 and Platform Event Errors

{% hint style="danger" %}
**Error: "No such column 'firstName' on sObject of type i42as\_\_OrderEvent\_\_e"**

This means a field referenced in the platform event doesn't exist on the `i42as__OrderEvent__e` object. Check:

* The field exists in Salesforce Setup > Platform Events > OrderEvent\_\_e > Custom fields
* The field name is spelled correctly (field names are case-sensitive)
* Custom fields end with `__c` (e.g., `firstName__c`, not `firstName`)
  {% endhint %}

{% hint style="danger" %}
**Error: "STRING\_TOO\_LONG"**

The content in a specific field exceeds the character limit set on the platform event field. Modify the field length in the platform event field definition in Salesforce Setup.

**Important:** Any platform event that triggers this error will not be resent and will be lost.
{% endhint %}

## Error Webhook for Automated Monitoring

Instead of manually checking process events, you can configure an **Error webhook** to be notified automatically when any plugin fails. This is useful for:

* Alerting your operations team via Slack, PagerDuty, or email
* Feeding failures into a data warehouse for tracking
* Triggering automated retry or recovery workflows

See [Webhooks and Notifications](https://docs.limio.com/integrations/order-orchestration/webhooks-and-notifications.md#error-webhook) for configuration details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limio.com/integrations/order-orchestration/troubleshooting-order-processing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
