When errors occur in web APIs, some of them are due to client mistakes, while others are due to issues outside the client’s control. Often the best solution to this second group of errors is to retry the same request at a later time in hopes of a different result. In this pattern, we’ll explore a mechanism by which clients can have clear direction in both how and when they retry requests that have previously failed due to errors on the API server.
It’s an inevitable fact of web APIs that some requests will fail—hopefully not the majority, but some nonetheless. Many of these failed requests will be due to client-side errors such as invalid request messages, while others might be due to failed preconditions and constraints being enforced on the API server. All of these types of errors share an important attribute: the problem is with the request itself violating some constraints or going against the API’s business logic. Put differently, if we replayed the same invalid request again, we should get the same error response. After all, the business logic typically doesn’t change from one moment to another.