Retry Is Not Recovery: A Practical Failure Model for Odoo Integrations

Владислав Червяков — Tue, 29 Sep 2026 11:33:38 +0000

An Odoo integration job fails. The first response is often: put it back in the queue.

That can repair a transient network failure. It can also create a second order, repeat a shipment update, or trigger an external side effect that already happened.

The direct answer is simple: retry repeats an operation; recovery restores a known, consistent state. Recovery may require a retry, but it may instead require replaying stored evidence, reconciling two systems, or stopping for a business decision.

This distinction is especially important in Odoo integrations because a local transaction boundary does not describe what happened on the other side of an HTTP, REST, or XML-RPC call.

A queue is an execution mechanism, not a recovery model

OCA's queue_job documentation describes background jobs, isolated transactions, retry patterns, channels, and job dependencies. These are valuable building blocks. They let an integration postpone work, control concurrency, and retry a job after a retryable exception.

But the queue cannot infer the business meaning of a failure.

Suppose an Odoo job sends a create request to another system. The receiver commits the new record, but the response is lost. Odoo sees a timeout and marks the job as failed. Running it again is technically correct from the queue's point of view. From the business point of view, it may create a duplicate.

Before choosing an action, classify the failure and establish what may already have happened.

A useful failure taxonomy

I use the following taxonomy as an operational tool, not as a claim about Odoo's internal exception hierarchy.

Failure class	Typical evidence	Safe automatic action	Main risk
Transport	timeout, connection reset, DNS failure	retry only after checking side effects	the remote system committed before the response was lost
Authentication	expired or rejected credentials	stop, repair credentials, then resume deliberately	repeated failures, lockout, or wrong identity
Schema mismatch	missing field, wrong type, unexpected payload shape	stop and fix the contract or mapping	corrupt or incomplete data
API contract mismatch	model or method is absent, signature changed	stop and verify the deployed API	retrying a request that can never succeed
Source-data error	missing required business data	correct the source record, then replay	bypassing validation and propagating bad data
Business conflict	state transition is no longer allowed	reconcile or route to a human	overwriting a valid newer state
Partial processing	some steps committed, later step failed	inspect checkpoints and reconcile	duplicates or contradictory state

The point of the table is not terminology. It is to prevent a single "retry" button from representing seven different operational decisions.

Retry, replay, and reconciliation answer different questions

Retry: can the same operation run again now?

A retry repeats the same operation, usually with the same input, after a temporary problem. It is appropriate when the failure is plausibly transient and the operation is safe to repeat.

"Safe" requires evidence. For a read, the answer is usually straightforward. For a write, ask:

Could the remote side already have committed?
Can the previous result be identified?
Does the receiver enforce a stable uniqueness or idempotency rule?
Which downstream effects would run again?

Exponential backoff can reduce load. It cannot answer any of those questions.

Replay: can we reprocess the original evidence after a fix?

Replay starts from a stored event, command, or source snapshot after correcting data, mapping, configuration, or code. It is not merely "run the failed function again."

A controlled replay needs:

the original input or an immutable reference to it;
the contract version used at the time;
a known restart point;
a check for an existing result;
an audit trail connecting the replay to the original attempt.

Replay is useful for deterministic faults. A renamed field or repaired mapping will not become correct through repeated retries, but the original event can often be processed successfully after the defect is fixed.

Reconciliation: do the systems agree now?

Reconciliation compares actual state across systems without trusting the job history as the full truth.

This is what finds an order that exists remotely while its local job says "failed," a shipment status that never returned, or a record created during partial processing. A reconciliation process normally matches stable identifiers, compares relevant fields or state, classifies differences, and either repairs them or creates an operator task.

Retries handle execution attempts. Reconciliation handles reality.

External identifiers help, but they are not idempotency

An external identifier creates a durable relationship between records in different systems. It lets an integration ask, "Have I already created the business object associated with this source record?"

That is necessary for duplicate prevention, but it is not sufficient. Formal idempotency depends on where uniqueness is enforced, whether lookup and create are atomic, how concurrent requests behave, and which side effects occur outside the protected boundary.

For example, this sequence is still racy:

Search the receiver for external ID X.
Find nothing.
Send a create request.

Two workers can pass step 2 before either creates the record. A database uniqueness constraint or receiver-side idempotency key closes a boundary that a preflight search alone does not.

Use external identifiers to locate prior results and correlate logs. Do not describe them as a complete idempotency guarantee unless the full write path supports that claim.

Two incident patterns from an Odoo-to-Odoo integration

During my time at kt.team, I worked on the architecture and development of an integration between two Odoo 18 Community instances for SPL. One instance represented the marketplace side; the other handled supplier execution. Orders, purchases, shipments, stock data, messages, and attachments moved through separate modules and queued jobs.

Two anonymized incidents illustrate why classification matters.

A field mismatch that retries could not repair

A stock synchronization job expected stock.move.line.qty_done, while the deployed contour used quantity in that specific incident context. This is not a universal rule for every Odoo installation; it was a mismatch between the integration's assumption and the actual model available in that contour.

The job was deterministic. Every retry repeated the same invalid assumption. The correct response was to inspect the deployed model, fix the mapping, and then replay the affected work.

An API method that did not exist on the target

Another job attempted to call a method on product.product that was absent from the marketplace-side API. Connectivity and authentication were working. The contract was wrong.

Again, retrying could not help. The integration needed to use the stock-update method actually exposed by the target, then reprocess the affected records under control.

Neither incident was a "queue problem." The queue surfaced the failures and preserved work, but recovery depended on understanding the deployed contract.

A six-step recovery decision

When an Odoo integration job fails, I use this sequence:

Preserve evidence. Keep the job identifier, source record, correlation data, error class, and relevant request metadata. Do not expose credentials or personal payloads in logs.
Classify the failure. Separate transport, authentication, schema, API contract, source data, business conflict, and partial processing.
Establish side effects. Determine what may have committed locally and remotely before the failure became visible.
Locate an existing result. Use external identifiers and receiver-side lookup before creating anything again.
Choose the operation. Retry a transient safe attempt, replay preserved evidence after a fix, or reconcile actual state. Escalate business conflicts instead of overwriting them.
Verify the final state. A green job is not enough. Confirm that both systems now agree on the business facts that matter.

The same model applies whether the transport is REST, XML-RPC, or another protocol. Protocol errors are observable symptoms; the recovery decision depends on business state and side effects.

Design for the failure path

Recoverability is an architectural property. It comes from stable identifiers, explicit ownership, preserved inputs, observable checkpoints, constrained side effects, and a reconciliation path.

Queues and retry policies remain useful. They are just one layer of the design.

If the only recovery instruction is "retry the failed job," the system does not yet have a recovery model. It has an execution mechanism and an assumption.

DEV Community: VCh Tech