@@ -90,8 +90,8 @@ Services must return a [`google.rpc.Status`][Status] message when an API
9090error occurs. For each error the service ** must** populate the ` message `
9191string in [ ` google.rpc.Status ` ] [ Status ] as follows:
9292
93- + present a developer-facing, human-readable "debug message"
94- + present the message in the service's native language to explain both
93+ - present a developer-facing, human-readable "debug message"
94+ - present the message in the service's native language to explain both
9595 the error and offer an actionable resolution to it ([ citation] [ Error
9696 model] )
9797
@@ -102,14 +102,14 @@ bases, such as StackOverflow™.
102102
103103Important points:
104104
105- + This ` message ` string is considered a problem description. It is
105+ - This ` message ` string is considered a problem description. It is
106106 intended for developers to understand the problem and is more
107107 detailed than [ ` ErrorInfo.reason ` ] [ ErrorInfo-reason ] , discussed in the
108108 next section.
109- + Use simple descriptive language that is easy to understand (without
109+ - Use simple descriptive language that is easy to understand (without
110110 technical jargon) to clearly state the problem that results in an
111111 error.
112- + For pre-existing (brownfield) APIs, the information in
112+ - For pre-existing (brownfield) APIs, the information in
113113 ` google.rpc.Status ` already exists and can’t be changed. In this
114114 case, do not edit anything in this ` google.rpc.Status ` , because some
115115 users might have automation running against the pre-existing content.
@@ -122,21 +122,21 @@ Important points:
122122Details of this object are summarized in the following fields, field
123123descriptions, and examples:
124124
125- + ` code int32 `
126- + The status code, which ** must** be an enum value of
125+ - ` code int32 `
126+ - The status code, which ** must** be an enum value of
127127 [ ` google.rpc.Code ` ] [ Code ] .
128- + * Example* : 8
129- + ` message string `
130- + A developer-facing error message, which ** should** be in English.
128+ - * Example* : 8
129+ - ` message string `
130+ - A developer-facing error message, which ** should** be in English.
131131 Any user-facing error message ** should** be located in the
132132 LocalizedMessage payload.
133- + * Example message* : \" The zone \' us-east1-a\' does not have enough
133+ - * Example message* : \" The zone \' us-east1-a\' does not have enough
134134 resources available to fulfill the request. Try a different zone, or
135135 try again later.\"
136- + ` details Object (repeated) `
137- + Additional text details about the error, which includes
136+ - ` details Object (repeated) `
137+ - Additional text details about the error, which includes
138138 ` ErrorInfo ` ,` LocalizedMessage ` , and so on.
139- + * Example* : Described in the [ ErrorDetails] ( #error-details ) section.
139+ - * Example* : Described in the [ ErrorDetails] ( #error-details ) section.
140140
141141#### [ ErrorDetails] [ details ]
142142
@@ -183,16 +183,16 @@ exactly one `ErrorInfo`. It is required.
183183Details of this object are summarized in the following fields, field
184184descriptions, and examples:
185185
186- + ` reason string `
187- + A short snake_case description of why the error occurred. Error
186+ - ` reason string `
187+ - A short snake_case description of why the error occurred. Error
188188 reasons are unique within a particular domain of errors. The error
189189 reason ** must** do the following:
190- + Be at most 63 characters and match a regular expression of
190+ - Be at most 63 characters and match a regular expression of
191191 ` /[A-Z][A-Z0-9_]+[A-Z0-9]/ ` , which represents UPPER_SNAKE_CASE.
192- + Be meaningful enough for a human reader to understand what the
192+ - Be meaningful enough for a human reader to understand what the
193193 reason refers to.
194- + Be unique and consumable by machine actors for automation.
195- + * Example* : CPU_AVAILABILITY<br >
194+ - Be unique and consumable by machine actors for automation.
195+ - * Example* : CPU_AVAILABILITY<br >
196196 Distill your error message into its simplest form. For example, the
197197 ` reason string ` could be one of the following text examples in
198198 UPPER_SNAKE_CASE: ` UNAVAILABLE ` , ` NO_STOCK ` , ` CHECKED_OUT ` ,
@@ -201,29 +201,31 @@ descriptions, and examples:
201201 > The Book, "The Great Gatsby", is unavailable at the Library,
202202 > "Garfield East". It is expected to be available again on 2199-05-13.
203203
204- + In contrast, using either of the following reasons is not
204+ - In contrast, using either of the following reasons is not
205205 recommended: ` THE_BOOK_YOU_WANT_IS_NOT_AVAILABLE ` , ` ERROR ` . And,
206206 using either of the following reasons breaches the required
207207 formatting and is not allowed: ` librariesAreGreat ` , ` noBooks ` .
208- + ` domain string `
209- + The logical grouping to which the ` reason ` belongs. The error domain
208+
209+ - ` domain string `
210+ - The logical grouping to which the ` reason ` belongs. The error domain
210211 is typically the registered service name of the tool or product that
211212 generated the error. The domain must be a globally unique value.
212- + * Example* :<br >` pubsub.googleapis.com `
213- + ` metadata map `
214- + Additional structured details about this error, which ** should**
213+ - * Example* :<br >` pubsub.googleapis.com `
214+
215+ - ` metadata map `
216+ - Additional structured details about this error, which ** should**
215217 provide important context for customers to identify resolution
216218 steps. Keys ** should** match ` /[a-z][a-zA-Z0-9-_]+/ ` , and be
217219 limited to 64 characters in length. When identifying the current
218220 value of an exceeded limit, the units ** should** be contained in the
219221 key, not the value.
220- + * Example* :
221- ```
222- "vmType": "e2-medium",
223- "attachment": "local-ssd=3,nvidia-t4=2",
224- "zone": "us-east1-a"
225- ```
226- + For guidance on using the metadata map, see [ Dynamic
222+ - * Example* :
223+ ```
224+ "vmType": "e2-medium",
225+ "attachment": "local-ssd=3,nvidia-t4=2",
226+ "zone": "us-east1-a"
227+ ```
228+ - For guidance on using the metadata map, see [Dynamic
227229 Variables](#dynamic-variables).
228230
229231##### Dynamic variables
@@ -301,18 +303,18 @@ will differ from the `message` string in `google.rpc.status`.
301303Details of this object are summarized in the following fields, field
302304descriptions, and examples:
303305
304- + ` locale string `
305- + The locale that follows the specification defined in [ IETF
306+ - `locale string`
307+ - The locale that follows the specification defined in [IETF
306308 bcp47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) (Tags for
307309 Identifying Languages).
308- + * Example* : ** "en-US"** , ** "fr-CH"** , ** "es-MX"**
309- + ` message string `
310- + The error message that the customer will receive through their
310+ - *Example*: **"en-US"**, **"fr-CH"**, **"es-MX"**
311+ - `message string`
312+ - The error message that the customer will receive through their
311313 chosen service, which **should** include a brief description of the
312314 error and a call to action to resolve the error. The message
313315 **should** include, where needed, data provided in other fields such
314316 as metadata.
315- + Give users clear and concise instructions for resolving the error,
317+ - Give users clear and concise instructions for resolving the error,
316318 which **must** be explicit as possible; for example:
317319
318320 > Consider trying your request in the <AVAILABLE-ZONE-1>,
@@ -321,11 +323,11 @@ descriptions, and examples:
321323 > again with a different VM hardware configuration or at a later
322324 > time.
323325
324- + If the error resolution exceeds the number of characters supported in
326+ - If the error resolution exceeds the number of characters supported in
325327 the problem description (`message` string of `google.rpc.Status`),
326- or requires multiple troubleshooting steps, include the most common
327- resolution in the message and use the ` Help ` payload to link to
328- relevant documentation.
328+ or requires multiple troubleshooting steps, include the most
329+ common resolution in the message and use the `Help` payload to
330+ link to relevant documentation.
329331
330332##### Help payload
331333
@@ -353,7 +355,7 @@ descriptions, and examples:
353355 - The URL of the link. For error documentation this must follow the
354356 standardized format listed in the following example.
355357 - *Example*:
356- https://cloud.google.com/PRODUCT/docs/ERROR-REASON
358+ https://cloud.google.com/PRODUCT/docs/ERROR-REASON
357359
358360### Error messages
359361
@@ -370,17 +372,17 @@ payload is present in the message.
370372If the error message contains ErrorInfo payload (a machine-readable
371373identifier):
372374
373- + ` Status.message ` * string* and ` LocalizedMessage.message ` * string* can
375+ - `Status.message` *string* and `LocalizedMessage.message` *string* can
374376 change
375- + New metadata fields can be added
376- + However, existing metadata fields ** must not** be removed and existing
377+ - New metadata fields can be added
378+ - However, existing metadata fields **must not** be removed and existing
377379 metadata field keys cannot be modified.
378380
379381If the error message does *not* contain ErrorInfo payload (usually for
380382pre-existing APIs):
381383
382- + The ` LocalizedMessage.message ` * string* can change
383- + However, the ` Status.message ` * string* ** must** not be changed, as
384+ - The `LocalizedMessage.message` *string* can change
385+ - However, the `Status.message` *string* **must** not be changed, as
384386 this change is backward-incompatible.
385387
386388##### Message alignment
@@ -469,17 +471,17 @@ message, which would be a backwards incompatible change.
469471
470472Reasons to present the same error message in both locations include the following:
471473
472- + The service plans to localize either immediately or in the near future. See,
473- "[ Localization] ( #localization ) ".
474- + This practice enables clients to find an error message consistently in one
474+ - The service plans to localize either immediately or in the near future. See,
475+ "[Localization](#localization)".
476+ - This practice enables clients to find an error message consistently in one
475477 location, `LocalizedMessaage.message`, across all methods of the API Service.
476478
477479Reasons to present an error message in `LocalizedMessage.message` that
478480differs from `Status.message` include the following:
479481
480- + The service requires an end-user-facing error message that differs
482+ - The service requires an end-user-facing error message that differs
481483 from the "debug message".
482- + Ongoing, iterative error message improvements are expected.
484+ - Ongoing, iterative error message improvements are expected.
483485
484486### Updating Status.message
485487
@@ -496,25 +498,25 @@ data instead.
496498
497499## Further reading
498500
499- + For which error codes to retry, see [ AIP-194] [ aip-194 ] .
500- + For how to retry errors in client libraries, see
501+ - For which error codes to retry, see [AIP-194][aip-194].
502+ - For how to retry errors in client libraries, see
501503 [AIP-4221][aip-4221].
502504
503505## Changelog
504506
505- + ** 2024-01-10** : Incorporate guidance for writing effective messages.
506- + ** 2023-05-17** : Change the recommended language for ` Status.message ` to be
507+ - **2024-01-10**: Incorporate guidance for writing effective messages.
508+ - **2023-05-17**: Change the recommended language for `Status.message` to be
507509 the service's native language rather than English.
508- + ** 2023-05-17** : Specify requirements for changing error messages.
509- + ** 2023-05-10** : Require [ ` ErrorInfo ` ] [ ErrorInfo ] for all error responses.
510- + ** 2023-05-04** : Require uniqueness by message type for error details.
511- + ** 2022-11-04** : Added guidance around PERMISSION_DENIED errors previously
510+ - **2023-05-17**: Specify requirements for changing error messages.
511+ - **2023-05-10**: Require [`ErrorInfo`][ErrorInfo] for all error responses.
512+ - **2023-05-04**: Require uniqueness by message type for error details.
513+ - **2022-11-04**: Added guidance around PERMISSION_DENIED errors previously
512514 found in other AIPs.
513- + ** 2022-08-12** : Reworded/Simplified intro to add clarity to the intent.
514- + ** 2020-01-22** : Added a reference to the [ ` ErrorInfo ` ] [ ErrorInfo ] message.
515- + ** 2019-10-14** : Added guidance restricting error message mutability to if
515+ - **2022-08-12**: Reworded/Simplified intro to add clarity to the intent.
516+ - **2020-01-22**: Added a reference to the [`ErrorInfo`][ErrorInfo] message.
517+ - **2019-10-14**: Added guidance restricting error message mutability to if
516518 there is a machine-readable identifier present.
517- + ** 2019-09-23** : Added guidance about error message strings being able to
519+ - **2019-09-23**: Added guidance about error message strings being able to
518520 change.
519521
520522<!-- prettier-ignore-start -->
0 commit comments