Partial Failures

When one request performs several pieces of work, a single success or failure label may not tell the whole story. Suppose a customer imports three reading lists: the service creates one, rejects one with an invalid name, and cannot save one because a storage partition is temporarily unavailable. Returning only “Import failed” hides the saved list. Returning only “Import succeeded” hides the other two outcomes. Repeating the entire request may create a duplicate of the list that already exists.

A partial failure occurs when some parts of a requested operation succeed while others fail or remain unresolved. A useful API makes those boundaries explicit and gives callers enough information to recover.

This chapter uses a fictional bookstore's JSON API over HTTPS to explain mixed outcomes, incomplete results, and recovery without losing track of completed work.