Failure handling
What happens when Brightpearl is down, slow, or rate-limiting, and how you'll know.
nohold is designed so that no order is ever lost. If Brightpearl is unreachable, slow, or rate-limiting, dispatches are queued and retried — silently from your team's perspective.
Retry policy
Every dispatch from nohold to Brightpearl is retry-safe:
- First attempt: immediate.
- If it fails (network error, 5xx, rate-limit), retry with exponential backoff: ~30s, 2m, 8m.
- After 4 total attempts, the dispatch lands in the dead-letter queue (DLQ).
Retries are deduplicated server-side — if the first call actually succeeded but the response was lost, the retry won't create a duplicate SO.
Circuit breaker
If Brightpearl is having a bad day (a string of consecutive failures across many merchants), nohold's circuit breaker opens. While the breaker is open:
- New dispatches fail fast without hitting Brightpearl, freeing up capacity.
- They're requeued and retried after the breaker closes.
- Your dashboard shows a yellow banner: "Brightpearl connectivity degraded".
When Brightpearl recovers, the breaker closes and the queue drains. You don't need to do anything.
Dead-letter queue
A dispatch reaches the DLQ only after retries are exhausted — usually because of a persistent error: invalid credentials, an account-level issue, a malformed payload.
You'll see DLQ entries on the dashboard's Splits view as red banners, with the failure reason. Common causes:
| Reason | What to do |
|---|---|
auth_invalid | Reconnect Brightpearl from Settings — your staff token may have been revoked. |
status_id_unknown | The configured BP status IDs don't exist on your account. Clear them in Settings to auto-discover, or set valid IDs. |
customer_not_found | The Shopify customer can't be matched in Brightpearl. Check the customer's email is consistent across systems. |
Once you've fixed the underlying issue, the dashboard offers a Replay button on each DLQ entry to re-attempt dispatch. The original retry counter resets and the dispatch goes back into the queue.
Sweeper
Independently of retries, a sweeper runs every two minutes to look for orphaned dispatches — rows that should have been processed but weren't (e.g. because of a deploy mid-flight). Anything it finds is re-enqueued.
You should never see this in action — it's belt-and-braces.
Rate limiting
To protect both nohold and Brightpearl, dispatches per merchant are capped at 50 per minute. In practice this is far above any real merchant's order rate. If you hit the limit, dispatches queue (no rejection) and clear within seconds.
What you'll notice as a merchant
Almost nothing. Day-to-day:
- ✅ Splits dashboard shows green "Dispatched" within a few seconds.
- ⚠️ Yellow banner during a Brightpearl incident — orders still queue safely.
- 🔴 Red DLQ banner only when something on your account needs attention (auth, config).
If you ever see something you don't understand, contact us with the Shopify order number — we can see exactly where the dispatch is in the pipeline.