Skip to content

Commit dfb35c4

Browse files
committed
PR feedback
1 parent 5b97082 commit dfb35c4

File tree

1 file changed

+2
-2
lines changed

1 file changed

+2
-2
lines changed

azure/ConsiderationsForServiceDesign.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,7 @@ status monitor LRO, whereas the status of all RELO operations is combined into t
230230
So status monitor LROs are "one-to-one" with their operation status, whereas RELO-style LROs are "many-to-one".
231231

232232
## 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 well designed 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.
234234

235235
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:
236236
- 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
239239

240240
There are two types of errors returned from your service and customers handle them differently.
241241
- 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.
243243

244244
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:
245245
- A `404` status code tells them the blob doesn't exist and the customer can report the error to their users

0 commit comments

Comments
 (0)