> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs and retry logic

> Recover Pix operations automatically with background jobs that retry failed events, reconcile refunds, and keep data consistent.

The Pix plugin recovers operations automatically with background jobs and retries. If a provider call times out or an event fails to process, the plugin retries and reconciles the data without manual work.

## Automatic retries

***

The plugin processes Pix events asynchronously. If it fails to process an event, the plugin retries in place, then captures the event to a dead-letter queue without loss. An operator replays a parked event, bounded to a maximum number of attempts. After the limit, the record stays parked for inspection and the plugin never drops it.

The plugin retries outbound calls to the provider on 5xx responses and timeouts. Each retry uses exponential backoff with jitter.

<Tip>
  The plugin deduplicates events by ID for a fixed time window. A retried or duplicate event never applies twice, so the jobs stay idempotent.
</Tip>

## Refund reconciliation

***

A refund can succeed at the provider but fail to record locally if the service crashes between the two steps. The refund reconciliation sweeper is a background safety net for this case.

The sweeper runs on a timer and finds refunds still stuck in pending. For each one, it re-drives the idempotent steps (settle, confirm, or close), which the provider deduplicates by refund reference. It parks a row still at the create step for an operator, because a blind create replay could cause a double refund.

```mermaid theme={null}
sequenceDiagram
  participant Sweeper
  participant Provider
  participant DB
  Sweeper->>DB: Find pending refund rows
  Sweeper->>Provider: Re-run the missing step
  alt Success
    Provider-->>Sweeper: confirmed
    Sweeper->>DB: Mark as done
  else Still failing
    Provider-->>Sweeper: error
    Sweeper->>DB: Record attempt and back off
  else Attempts exhausted
    Sweeper->>DB: Park row and raise alert
  end
```

Each failed attempt waits longer than the last, from one minute up to one hour. After a maximum number of attempts, the sweeper parks the record and raises an alert. It does not retry forever. The sweeper is optional and off by default.

## Configuration

***

You can tune retry and reconciliation behavior with environment variables:

| Variable                                     | Description                                                              | Default |
| :------------------------------------------- | :----------------------------------------------------------------------- | :------ |
| `DLQ_REPLAY_MAX_ATTEMPTS`                    | Times an operator can replay a parked event before it stays parked       | 3       |
| `CONSUMER_DEDUP_TTL_SEC`                     | Deduplication window, in seconds, that keeps event processing idempotent | 3600    |
| `REFUND_RECONCILIATION_SWEEPER_ENABLED`      | Turns on the refund reconciliation sweeper                               | false   |
| `REFUND_RECONCILIATION_SWEEPER_INTERVAL_SEC` | Time, in seconds, between sweeps                                         | 30      |
| `REFUND_RECONCILIATION_SWEEPER_MAX_ATTEMPTS` | Attempts before the sweeper parks a record and raises an alert           | 10      |

## What you need to do

***

The plugin manages retries and reconciliation for you. The default settings fit most deployments. To keep operations healthy:

* Use unique, traceable IDs for your transactions and accounts.
* Monitor event delivery and transaction status.
* Contact Lerian for job visibility or event replay support.