Add HTTP upload idempotency support

docs/troubleshooting.md

@@ -451,6 +451,26 @@ Safe fix: send one valid tar or tar.gz source bundle archive with `Content-Type:
 
 Reference: [Operations](operations.md#http-upload-operation).
 
+## Upload Idempotency Conflict
+
+Symptom: `POST /upload` returns `409`.
+
+Likely cause: the request reused an `Idempotency-Key` for the same authenticated pipeline with a different source manifest, or another request with the same key is still being staged before its manifest is known.
+
+Diagnostic:
+
+```sh
+curl -i -X POST http://127.0.0.1:8080/upload \
+  -H "Authorization: Bearer $DISTRIBUTOR_UPLOAD_TOKEN" \
+  -H "Content-Type: application/gzip" \
+  -H "Idempotency-Key: <key>" \
+  --data-binary @bundle.tar.gz
+```
+
+Safe fix: if the response includes `"retryable":true`, retry the same upload later with the same key. Otherwise, inspect the producer operation and use the same key only for the same source bundle.
+
+Reference: [HTTP Upload API Contract](integrations/http-upload.md#post-upload).
+
 ## Upload Status Is Missing
 
 Symptom: `GET /runs/<run_id>` returns `404`.