Make error paths explicit

README.md

@@ -105,6 +105,26 @@ Tested on the same machine with shared nginx volumes:
 
 Both are bottlenecked by nginx volume I/O. The index layer (SQLite) can sustain 378,000 writes/sec in isolation.
 
+## Error responses
+
+Every error returns a plain-text body with a human-readable message.
+
+| Status | Error | When |
+|--------|-------|------|
+| `404 Not Found` | `not found` | GET, HEAD, DELETE for a key that doesn't exist |
+| `500 Internal Server Error` | `corrupt record for key {key}: no volumes` | Key exists in index but has no volume locations (data integrity issue) |
+| `500 Internal Server Error` | `database error: {detail}` | SQLite failure (disk full, corruption, locked) |
+| `502 Bad Gateway` | `not all volume writes succeeded` | PUT where one or more volume writes failed; all volumes are rolled back |
+| `503 Service Unavailable` | `need {n} volumes but only {m} available` | PUT when fewer volumes are configured than the replication factor requires |
+
+### Failure modes
+
+**PUT** writes to all target volumes concurrently, then updates the index. If any volume write fails, all volumes are rolled back (best-effort) and the client gets 502. If volume writes succeed but the index update fails, volumes are rolled back and the client gets 500.
+
+**DELETE** removes the key from the index and issues best-effort deletes to all volumes. Volume delete failures are logged but do not fail the request — the client always gets 204 if the key existed. This can leave orphaned blobs on volumes; use `rebuild` to reconcile.
+
+**GET** looks up the key in the index and returns a 302 redirect to the first volume. If the volume is unreachable, the client sees the failure directly from nginx (the index server does not proxy the blob).
+
 ## Security
 
 mkv assumes a **trusted network**. There is no built-in authentication, authorization, or encryption. This is the same security model as minikeyvalue — neither system is designed for direct exposure to the public internet.