Skip to content

Integration Error Codes

Applies to: ERP Write-back · Which modules do I have?

Purpose

Interpret a write-back delivery failure: what Complifly attempted, what happened, whether the event is safe, and who resolves it.

Audience

Integration developers, administrators, support teams.

Prerequisites

Reference

The failures

Error Meaning Fixed by Event state
Endpoint unreachable No answer from your endpoint — network, DNS, or the service is down admin Retries continue automatically
Endpoint refused The endpoint was rejected before any call was made — it failed a safety check, typically because it is not HTTPS admin Nothing was sent
ERP rejected the update Your endpoint answered, and refused the content you Retrying identical data will not change the answer
Authentication failed Your ERP rejected Complifly's credentials admin Paused and queued — nothing is lost
Delivery gave up Every retry is spent support Held, not deleted, pending a decision

The distinction that matters

These five failures divide into three genuinely different situations, and treating them alike wastes effort:

Situation Errors What to do
We could not reach you Unreachable, refused Fix connectivity or the endpoint configuration. Events are safe and will resume
You said no Rejected Retrying is pointless. Something about the content or the endpoint's expectations is wrong. Fix, then replay
We gave up Dead Investigate, fix, then replay explicitly

Endpoint refused is worth calling out. Nothing was sent — the endpoint failed a check before any call was attempted, most often because it is not HTTPS. This is a configuration error, discovered before any data left, which is the intended behaviour.

No event is lost

Every state above holds the event. Retries continue, an authentication failure pauses and queues rather than discarding, and even an exhausted event is held pending a decision rather than deleted.

The one real risk is retention: dead-lettered events are kept for a configured period. If that period is shorter than your realistic reaction time — a weekend, a holiday — the evidence is purged before anyone investigates. Check the setting against how quickly you actually respond. See Environment Variables.

The circuit breaker

After consecutive failures, delivery to that endpoint pauses for a cooldown, then resumes. This protects the dispatcher from an endpoint that is down; it does not lose events.

A sudden stop in deliveries after a burst of failures is the circuit breaker doing its job, not a fault. Fix the endpoint and delivery resumes.

Recovering

Situation Recovery
Endpoint fixed, events queued They resume automatically after cooldown
Events dead-lettered An administrator replays them
Many events affected Preview the requeue first, then requeue
A very large backlog Pause the consumer, requeue in batches, resume
Uncertain what was missed Reconcile by document status rather than replaying blindly

Always preview before requeuing. A requeue with a wider scope than intended replays a large volume into a consumer that may not be ready for it — a self-inflicted incident on top of the original one.

Validation

Check Pass condition
Failure alerts reach a person Configured and tested, addressed to a distribution list
Delivery logs are readable An administrator can see attempts and outcomes
Dead-letter retention exceeds reaction time Confirmed against how quickly you actually respond
Replay works Tested in a non-production environment
Preview used before requeue Part of the documented procedure
The consumer is idempotent A replayed event is processed once
Backlog age is monitored Alert configured on rising age, not on count

Troubleshooting

Symptom Cause Action
Deliveries stopped after a burst of failures Circuit breaker opened Expected. Fix the endpoint; delivery resumes after cooldown
Endpoint refused before any call It failed a safety check, typically not being HTTPS Correct the endpoint configuration. Never enable insecure delivery in production
Endpoint unreachable but the ERP is running Network path, DNS, or certificate Test the endpoint from outside your network, exactly as Complifly would call it
ERP rejects every event A content or contract mismatch Inspect a rejected payload against what the ERP expects
Authentication failed ERP credentials changed or expired Update them. Events are queued, not lost
Events dead-lettered Retries exhausted during a long outage Fix the cause, then replay
Dead-lettered events gone before investigation Retention shorter than reaction time Raise the retention
A requeue flooded the consumer Requeued without previewing Preview first; pause the consumer before a large replay
Events processed twice after replay Consumer not idempotent Deduplicate on the event identifier
Nobody noticed delivery had stopped Alerts disabled, or addressed to an individual who has left Enable alerts; use a distribution list
ERP out of step after a long outage Some events never applied Reconcile by document status, then replay what is genuinely missing