Training
Module
Implement resiliency in a cloud-native microservice - Training
This module guides you through implementing resiliency in an .NET microservices app in a Kubernetes Service.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Kiota API clients include error types for errors defined in OpenAPI descriptions.
The abstractions library for each language defines an API exception type (or error) which inherits or implements the default error/exception type for the language. Kiota generates types for schemas mapped to HTTP specific error status codes (400-600) or to ranges (4XX, 5XX).
Note
If the error schema is an allOf
, Kiota will flatten all the allOf
entries recursively into the generated type as most languages do not support multiple parents inheritance.
This mapping of codes to types is passed to the request adapter as a dictionary/map so it can be used at runtime and is specific to each endpoint. An error mapping is only considered valid if the response has a schema of type object
and at least one field. All generated error/exception types inherit from the base API exception/error defined in the abstractions library.
At runtime, if the API returns an error status code, the request adapter follows this sequence:
The generated clients throw exceptions/errors for failed response codes to allow the consumer to tell the difference between a successful response that didn't return a body (204, etc.) and a failed response. The consumer can implement try/catch behavior that either catches the generic API exception type, or is more specific to an exception type mapped to a range or even a status code, depending on the scenario.
Most request adapters handle transient errors (for example 429
because of throttling, network interruption, etc.) through two main mechanisms. In this scenario, the request adapter and the generated client aren't aware that an error happened and don't throw an exception.
Kiota generates code to extract the value of a property from the generated error type as the main exception/error message/reason if a string property is identified with the x-ms-primary-error-message
extension.
In this example, the value for the errorMessage property returned from the API is used as the error message for the exception if any 404 response is returned.
openapi: 3.0.3
info:
title: OData Service for namespace microsoft.graph
description: This OData service is located at https://graph.microsoft.com/v1.0
version: 1.0.1
paths:
/foo:
get:
responses:
'404':
content:
application/json:
schema:
type: object
properties:
bar:
type: string
errorMessage:
type: string
x-ms-primary-error-message: true
servers:
- url: https://graph.microsoft.com/v1.0
The base API exception/error type from which all generated error types derive defines the following properties. The request adapter for the language automatically populates these properties.
Name | Type | Description |
---|---|---|
ResponseStatusCode | int32 | The status code from the HTTP response. |
ResponseHeaders | map(string, string[]) | The response headers. |
Additionally these types also derive from the native exception/error type of the platform, and can be expected to provide the same properties.
When a description doesn't document a mapping for an error status code encountered at runtime, the client application receives an exception/error with the following error message: "The server returned an unexpected status code and no error factory is registered for this code." There are many ways to deal with this situation:
Training
Module
Implement resiliency in a cloud-native microservice - Training
This module guides you through implementing resiliency in an .NET microservices app in a Kubernetes Service.