Error handling and retries in Boomi integrations
Transient vs permanent errors, retries with backoff, a review queue for what needs a human, and alerts: a practical error-handling design, built step by step in Boomi Integration.
Every integration fails sometimes. The ERP is restarted for an update, a cloud API returns 503 for a minute, a
customer types a VAT number with a space in it. The difference between a reliable integration and a fragile one is not
whether errors happen, but what the flow does next. This article describes a simple error-handling design that works
for most business flows, then builds it in Boomi.
Why “log it and move on” fails
The default behaviour of many integrations is one of two extremes:
- Stop everything. One bad invoice blocks the whole batch, and 199 good invoices wait for someone to fix one.
- Log and continue. The error is written to a log nobody reads. The order is lost, and you find out at month end when the numbers don’t match.
Retrying blindly doesn’t help either. Retrying a missing product code a hundred times won’t create the product, and retrying a timeout immediately, while the ERP is restarting, just adds load.
The pattern: classify, retry, park, alert
1. Classify the error
Errors fall into two groups, and they need opposite treatment:
| Type | Examples | What to do |
|---|---|---|
| Transient | timeout, connection refused, HTTP 429, 502, 503, 504, locked record |
retry later |
| Permanent | HTTP 400, 404, 422, validation error, unknown product code, missing VAT number |
don’t retry, send to a human |
Authentication errors (401, 403) are a special case: retrying won’t help, but the cause is usually a configuration
problem (an expired password or token) that affects every document, so they deserve an immediate alert.
2. Retry transient errors with backoff
Retry a few times with growing pauses, for example after 10 seconds, 1 minute and 5 minutes. This is called backoff. It gives the other system time to recover and avoids hammering it. Retries are only safe if the operation is idempotent, so a retried create doesn’t produce a duplicate (see Syncing e-shop orders to your ERP with Boomi).
3. Park what can’t be fixed automatically
Documents that fail permanently, or still fail after all retries, go to a review queue (often called a dead-letter queue). It keeps the original data, the error message and a timestamp, so someone can fix the cause and re-submit. Crucially, one parked document doesn’t stop the others.
4. Alert the right people, once
Send an alert that says what failed, why and what to do, to the team that can act on it. Group alerts: one email saying “12 orders failed: unknown product code” is useful, 12 separate emails are spam that people learn to ignore.
Building it in Boomi
We will wrap the “create order in ERP” step from the previous article with this design. The building blocks are the Try/Catch shape, a Decision on the error type, a sub-process for the review queue and the platform’s own alerting.
Step 1: Wrap the risky step in Try/Catch
- Place a Try/Catch shape before the ERP connector. Everything on the Try path is protected.
- Set the failure trigger to catch document-level errors, so one failing order is caught on its own while the others continue.
- The Try/Catch shape has a retry count setting. When it is above zero, failed documents are re-run through the Try path before reaching the Catch path, with a growing delay between attempts. This gives you a basic backoff without extra design. Check the current documentation for the maximum retry count and the delays for your release.
Built-in retries are a good start for short outages. For outages that last longer than a few minutes, use the review queue below and re-submit later, instead of keeping the execution waiting.
Step 2: Make connector errors visible
By default, many connectors treat an HTTP error response as a failed document, which is what you want here. For connectors where you can choose, make sure errors are raised rather than returned as a normal response, otherwise the Try/Catch has nothing to catch. When you need the status code in your logic, read it from the connector’s response document properties (the exact property names vary by connector).
Step 3: Classify on the Catch path
On the Catch path, the error message is available to the process (the Try/Catch shape sets it as a document property). Add a Decision or Route shape that looks at it:
- Messages that match timeouts, connection errors or status codes such as
503go to the transient branch. - Everything else goes to the permanent branch.
Start with a short list of patterns and refine it after a few weeks in production, when you know which errors your systems really return.
Step 4: Build the review queue
Create a small sub-process, called with a Process Call shape from both branches once retries are exhausted. It should:
- Save the original document together with the error, the process name and the order reference (for example
ESHOP-58213). The destination can be a database table, a shared folder, an Atom Queue or an event stream topic. Pick the one your team will actually look at. - Mark the record as
NEW, so a re-submit process (or a person) can pick it up later and change it toRESUBMITTEDorCLOSED.
Boomi’s Process Reporting also lets you inspect failed documents, and for some process types re-run them. That is useful for operators, but a separate review queue gives business users a list they can work with without access to the platform.
Step 5: Alert
You have two layers:
- Inside the process: a Notify shape on the permanent branch writes a message with a clear text (for example “Order ESHOP-58213: product code SKU-771 not found in ERP”). Notifications can be picked up by the platform’s alerting and email subscriptions.
- Platform level: configure email alerts or event subscriptions for process errors and runtime problems (for example a runtime that goes offline), so you hear about failures that never reach your Catch path.
If you want a process to end as failed after it parks the documents, so it is clearly visible in monitoring, add an Exception shape at the end of the permanent branch.
Before you go live
- Break things on purpose. Point the ERP connection to a wrong port, send an order with an unknown product code and check that each one ends up in the right branch, with a useful message.
- Test the retry path for duplicates. Simulate a timeout after the ERP has created the order and confirm that the retry doesn’t create a second one.
- Agree on ownership. Decide who looks at the review queue and how often. A queue nobody owns is just a slower version of “log and move on”.
- Track the numbers. Count retries and parked documents per week. A sudden rise usually means something changed in one of the systems.
For a deeper look at monitoring and alerting across all your processes, see Monitoring and alerts for Boomi integrations.
Summary
Classify errors, retry only the transient ones with backoff, park the rest where a person can fix and re-submit them, and alert once with a message someone can act on. In Boomi, the Try/Catch shape provides the retry and catch logic, a Decision shape classifies, and a small sub-process gives you a review queue. For the bigger picture, see our guide Application integration: connecting ERP, CRM and e-shop without the spaghetti.
