HTTP 409 Conflict — Cause e soluzioni

Cosa significa HTTP 409

HTTP 409 Conflict significa che il server ha capito la richiesta ma non può applicarla perché contraddice lo stato attuale della risorsa di destinazione. L'esempio classico è una collisione di modifica: due client hanno caricato lo stesso documento, entrambi salvano, e il secondo salvataggio sovrascriverebbe silenziosamente il primo.

A differenza del 400, la richiesta in sé è ben formata — reinviarla invariata potrebbe persino avere successo in seguito. Il corpo della risposta dovrebbe spiegare cosa è in conflitto, così il client (o l'utente) può risolverlo e riprovare.

Cause comuni degli errori 409

Una collisione di modifica: la risorsa è stata modificata da qualcun altro da quando il client l'ha recuperata l'ultima volta (spesso visibile tramite ETag / If-Match).
Creare una risorsa già esistente — nome utente, email, slug o nome file duplicato.
Una discrepanza di versione nell'optimistic locking: il numero di versione inviato è obsoleto.
Eliminare o spostare una risorsa che ha dipendenti che il server rifiuta di rendere orfani.
Passi di un workflow concorrente applicati fuori ordine (ad esempio, approvare un ordine già annullato).

Come risolverlo da sviluppatore

Leggi il corpo della risposta — una buona API indica il campo in conflitto o la versione attuale attesa.
Recupera nuovamente la risorsa, riapplica la tua modifica sullo stato aggiornato e reinvia la richiesta.
Usa richieste condizionali (If-Match con ETag) in modo che i conflitti vengano rilevati in modo affidabile invece di sovrascrivere i dati.
Per i conflitti di creazione duplicata, decidi l'idempotenza in anticipo: restituisci la risorsa esistente, oppure 409 con un riferimento ad essa.

Esempio di risposta

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":"conflict","message":"document was modified by another user","current_version":42}

FAQ

Qual è la differenza tra 409 e 400?

400 significa che la richiesta stessa è malformata o non valida. 409 significa che la richiesta va bene, ma entra in conflitto con lo stato attuale della risorsa — riprovare dopo aver risolto il conflitto può avere successo.

Quando un'API dovrebbe restituire 409 invece di 422?

Usa 422 per gli errori di validazione all'interno del payload e 409 per le collisioni con lo stato esistente lato server, come duplicati o versioni obsolete.

In che modo gli ETag aiutano a evitare gli errori 409?

Il client invia If-Match con l'ETag visto l'ultima volta; il server applica la modifica solo se la risorsa non è cambiata, altrimenti restituisce 409 (o 412) invece di sovrascrivere.