You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: azure/ConsiderationsForServiceDesign.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -230,7 +230,7 @@ status monitor LRO, whereas the status of all RELO operations is combined into t
230
230
So status monitor LROs are "one-to-one" with their operation status, whereas RELO-style LROs are "many-to-one".
231
231
232
232
## Errors
233
-
One of the most important parts of service design is also one of the most overlooked. The errors returned by your service are a critical part of your developer experience. Your service and your customer's application together form a distributed system. Errors are inevitable, but welldesigned errors enabling customers to self-diagnose and recover from faults won't take down their applications or incur overwhelming customer support costs for you.
233
+
One of the most important parts of service design is also one of the most overlooked. The errors returned by your service are a critical part of your developer experience. Your service and your customer's application together form a distributed system. Errors are inevitable, but well-designed errors can help you avoid costly customer support incidents by empowering customers to self-diagnose problems.
234
234
235
235
First, you should always try to design errors out of existence if possible. You'll get a lot of this for free by following the Guidelines. Some examples include:
236
236
- Idempotent APIs solve a whole class of network issues where customers have no idea how to proceed if they send a request to the service but never get a response.
@@ -239,7 +239,7 @@ First, you should always try to design errors out of existence if possible. You
239
239
240
240
There are two types of errors returned from your service and customers handle them differently.
241
241
- Usage errors where the customer is calling your API incorrectly. The customer can easily make these errors go away by fixing their code. We expect most usage errors to be found during testing.
242
-
- Runtime errors that can't be prevented by the customer and need to be recovered from. Some runtime errors like `429` throttling will be handled automatically by client libraries, but most will be situations like a `409` conflict that requires knowledge about the customer's application to remedy.
242
+
- Runtime errors that can't be prevented by the customer and need to be recovered from. Some runtime errors like `429` throttling will be handled automatically by client libraries, but most will be situations like a `409` conflict requiring knowledge about the customer's application to remedy.
243
243
244
244
We provide appropriate [HTTP status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) for customers to handle errors generically and error code strings in our common error schema and the `x-ms-error-code` header for customers to handle errors specifically. As an example, consider what a customer would do when trying to get the properties of a Storage blob:
245
245
- A `404` status code tells them the blob doesn't exist and the customer can report the error to their users
0 commit comments