409 conflict errors on wallet update due to concurrent requests

If your integration is receiving 409 Conflict errors when calling PUT /api/v1/wallets/:lago_id, the most likely cause is concurrent requests modifying the same wallet at the same time. Lago uses row-level locking on wallet records to maintain balance integrity. When two operations attempt to modify the same wallet simultaneously, the second request fails with a 409 rather than silently overwriting the first.

How wallet locking works

The wallet record in Lago tracks live balance state (credits_balance, ongoing_balance_cents, etc.) alongside configuration fields like top-up thresholds, expiry, and payment method. Both balance updates (triggered by usage consumption or top-ups) and configuration updates (triggered by API calls to update the wallet) acquire a row-level lock on the wallet record. If a balance recalculation is in progress, for example triggered by an event being processed, and an API call to update the wallet configuration arrives at the same moment, the second operation detects the lock and returns a 409 Conflict.

This is most common in high-throughput integrations that send usage events at high frequency while also updating wallet thresholds programmatically, or that run parallel background jobs triggering both balance refreshes and wallet configuration updates.

How to resolve the issue

Serialize wallet update requests. If your integration needs to update wallet configuration, implement a retry with exponential backoff on 409 responses: wait a short interval and retry the same request. Do not fire multiple wallet update calls in parallel for the same wallet.

If the 409 errors persist beyond isolated retries, review whether your event ingestion pipeline is triggering frequent wallet balance recalculations that overlap with configuration updates, and consider batching or sequencing those operations.

How to prevent this from happening again

Treat wallet update API calls as serialized operations per wallet. Use a queue or mutex in your integration layer to ensure only one wallet update for a given lago_id is in flight at any time.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.