Retryable vs Non-Retryable Errors

After a request fails, trying again can be either helpful or harmful. A bookstore's catalog read might succeed after maintenance ends. An order submission that times out is less straightforward: the customer sees no confirmation, but the order may already exist. Repeating that request could create a second order.

Both failures may be temporary, but they require different decisions. A useful retry policy considers the cause of failure, the effect of repeating the operation, and whether the caller can afford another attempt.

This chapter uses a fictional JSON API over HTTPS to explain those decisions and how an API can help clients make them.