Skip to content

Commit 7db5a22

Browse files
committed
Clarify error response structure and casing for acronyms
1 parent c737442 commit 7db5a22

File tree

1 file changed

+29
-4
lines changed

1 file changed

+29
-4
lines changed

azure/Guidelines.md

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ Because of this, required fields can only be introduced in the 1st version of a
238238

239239
:white_check_mark: **DO** make fields simple and maintain a shallow hierarchy.
240240

241-
:white_check_mark: **DO** use camel case for all JSON field names.
241+
:white_check_mark: **DO** use camel case for all JSON field names. Do not upper-case acronyms; use camel case.
242242

243243
:white_check_mark: **DO** treat JSON field names with case-sensitivity.
244244

@@ -282,17 +282,42 @@ There are 2 kinds of errors:
282282
- An error where you expect customer code to gracefully recover at runtime
283283
- An error indicating a bug in customer code that is unlikely to be recoverable at runtime; the customer must just fix their code
284284

285-
:white_check_mark: **DO** return error an `x-ms-error-code` response header with a string value indicating what went wrong.
285+
:white_check_mark: **DO** return an `x-ms-error-code` response header with a string error code indicating what went wrong.
286286

287287
*NOTE: Error code values are part of your API contract (because customer code is likely to do comparisons against them) and cannot change in the future.*
288288

289289
:white_check_mark: **DO** carefully craft `x-ms-error-code` string values for errors that are recoverable at runtime.
290290

291-
:white_check_mark: **DO** ensure that the top-level `code` field's value is identical to the `x-ms-error-code` header's value (see example body below).
291+
:white_check_mark: **DO** ensure that the top-level `code` field's value is identical to the `x-ms-error-code` header's value.
292292

293293
:white_check_mark: **DO** document the service's error code strings; they are part of the API contract.
294294

295-
:white_check_mark: **DO** provide a response body as follows (example):
295+
:white_check_mark: **DO** provide a response body with the following structure:
296+
297+
**ErrorResponse** : Object
298+
299+
Property | Type | Required | Description
300+
-------- | ---- | -------- | -----------
301+
`error` | ErrorDetail | ✔ | The error object.
302+
303+
**ErrorDetail** : Object
304+
305+
Property | Type | Required | Description
306+
-------- | ---- | -------- | -----------
307+
`code` | String | ✔ | One of a server-defined set of error codes.
308+
`message` | String | ✔ | A human-readable representation of the error.
309+
`target` | String | | The target of the error.
310+
`details` | ErrorDetail[] | | An array of details about specific errors that led to this reported error.
311+
`innererror` | InnerError | | An object containing more specific information than the current object about the error.
312+
313+
**InnerError** : Object
314+
315+
Property | Type | Required | Description
316+
-------- | ---- | -------- | -----------
317+
`code` | String | | A more specific error code than was provided by the containing error.
318+
`innererror` | InnerError | | An object containing more specific information than the current object about the error.
319+
320+
Example:
296321
```json
297322
{
298323
"error": {

0 commit comments

Comments
 (0)