Guidance on handling concurrent HTTP aggregate writes (avoiding 500 responses)

[KorzhovAlexander]

Hi!

I’m using Wolverine HTTP endpoints together with Marten aggregate workflows,
and I’d like to clarify the recommended approach for handling concurrency
conflicts in synchronous HTTP scenarios.

Context

We have HTTP endpoints that write to a Marten event stream using the
aggregate workflow (e.g. [Aggregate] / [WriteAggregate]).
https://wolverinefx.net/guide/durability/marten/event-sourcing.html#aggregate-handlers-and-event-sourcing
At the same time, the same aggregate can also receive events from asynchronous
processes (background jobs, message handlers,other endpoints etc.).

When two HTTP requests (or HTTP + async handler) attempt to append events
to the same stream concurrently, Marten throws an optimistic concurrency
exception (e.g. EventStreamUnexpectedMaxEventIdException), which results
in a 500 HTTP response.

From my understanding, this is expected and correct behavior from
an optimistic concurrency standpoint, and not a bug.

But the question

From an API design perspective, this can be surprising for users, because:

• the aggregate workflow works very smoothly for single-request scenarios
• but concurrent HTTP requests to the same aggregate can produce 500 responses
• even though the system is functioning correctly and protecting consistency

What is the recommended pattern in Wolverine for this situation?

For example:

• mapping concurrency exceptions to a non-500 HTTP status (e.g. 409)?
• avoiding synchronous HTTP writes and routing HTTP → async commands instead?
• using exclusive stream locks for HTTP endpoints?
• any built-in guidance or patterns to prevent exposing concurrency conflicts as 500s?

Why I’m asking

I want to make sure I’m aligning with the intended usage of Wolverine + Marten,
and also avoid teaching my team to treat optimistic concurrency exceptions
as “bugs”, when they are actually expected signals.
I understand that it is possible to use retries in the request bus, but I haven't found a built-in way to do this in the HTTP API. https://wolverinefx.net/tutorials/concurrency.html#dealing-with-concurrency

Any guidance or documentation pointers would be very helpful.

Thanks!

Files

Demo parallel events from http by stream https://github.com/KorzhovAlexander/demo-parallel-http-wolverine-events/tree/main