Respostas de erros e tipos de recurso do Microsoft GraphMicrosoft Graph error responses and resource types

• 13/03/2021
• 7 minutos para o fim da leitura
• • M
  • o

Os erros no Microsoft Graph serão retornados por meio de códigos de status HTTP padrão, bem como um objeto de resposta de erro JSON.Errors in Microsoft Graph are returned using standard HTTP status codes, as well as a JSON error response object.

Códigos de status de HTTPHTTP status codes

A tabela a seguir lista e descreve os códigos de status HTTP que podem ser retornados.The following table lists and describes the HTTP status codes that can be returned.

A resposta de erro é um único objeto JSON que contém uma propriedade única chamada error. Esse objeto inclui todos os detalhes do erro. Você pode usar as informações retornadas aqui em vez de ou além do código de status HTTP. Este é um exemplo de um corpo de erro JSON completo.The error response is a single JSON object that contains a single property named error. This object includes all the details of the error. You can use the information returned here instead of or in addition to the HTTP status code. The following is an example of a full JSON error body.

{
  "error": {
    "code": "invalidRange",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "requestId": "request-id",
      "date": "date-time"
    }
  }
}

Tipo de recurso de erroError resource type

O recurso de erro será retornado sempre que ocorrer um erro no processamento de uma solicitação.The error resource is returned whenever an error occurs in the processing of a request.

Respostas de erro seguem a definição na especificação OData v4 para respostas de erro.Error responses follow the definition in the OData v4 specification for error responses.

Representação JSONJSON representation

O recurso de erro é composto por estes recursos:The error resource is composed of these resources:

{
  "error": { "@odata.type": "odata.error" }  
}

Tipo de recurso odata.errorodata.error resource type

Dentro da resposta de erro há um recurso de erro que inclui as seguintes propriedades:Inside the error response is an error resource that includes the following properties:

{
  "code": "string",
  "message": "string",
  "innererror": { "@odata.type": "odata.error" }
}

Propriedade de códigoCode property

A propriedade code contém um dos valores possíveis a seguir. Seus aplicativos devem estar preparados para lidar com qualquer um destes erros.The code property contains one of the following possible values. Your apps should be prepared to handle any one of these errors.

O objeto innererror pode conter repetidamente mais objetos innererror com códigos de erro adicionais, mais específicos. Ao lidar com um erro, os aplicativos devem percorrer todos os códigos de erro disponíveis e usar o mais detalhado que consigam entender. Alguns dos códigos mais detalhados estão listados na parte inferior desta página.The innererror object might recursively contain more innererror objects with additional, more specific error codes. When handling an error, apps should loop through all the error codes available and use the most detailed one that they understand. Some of the more detailed codes are listed at the bottom of this page.

Para verificar se um objeto de erro é um erro que você está esperando, execute um loop sobre os objetos innererror procurando os códigos de erro que você espera. Por exemplo:To verify that an error object is an error you are expecting, you must loop over the innererror objects, looking for the error codes you expect. For example:

public bool IsError(string expectedErrorCode)
{
    OneDriveInnerError errorCode = this.Error;
    while (null != errorCode)
    {
        if (errorCode.Code == expectedErrorCode)
            return true;
        errorCode = errorCode.InnerError;
    }
    return false;
}

Para um exemplo que mostra como lidar de maneira apropriada com erros, consulte Tratamento de Código de Erro.For an example that shows how to properly handle errors, see Error Code Handling.

A propriedade message na raiz contém uma mensagem de erro destinada ao desenvolvedor. As mensagens de erro não são localizadas e não devem ser exibidas diretamente para o usuário. Ao tratar de erros, seu código não deve desviar dos valores message porque eles podem mudar a qualquer momento e geralmente contêm informações dinâmicas específicas para a solicitação com falha. Você só deve escrever códigos contra códigos de erro retornados nas propriedades code.The message property at the root contains an error message intended for the developer to read. Error messages are not localized and shouldn't be displayed directly to the user. When handling errors, your code should not key off of message values because they can change at any time, and they often contain dynamic information specific to the failed request. You should only code against error codes returned in code properties.

Códigos de erro detalhadosDetailed error codes

A seguir estão alguns erros adicionais que seu aplicativo pode encontrar nos objetos aninhados innererror. Os aplicativos não são obrigados a tratar deles, mas podem, se quiserem. O serviço pode adicionar novos códigos de erro ou parar de retornar os antigos a qualquer hora; portanto, é importante que todos os aplicativos consigam tratar dos códigos de erro básicos.The following are some additional errors that your app might encounter within the nested innererror objects. Apps are not required to handle these, but can if they choose. The service might add new error codes or stop returning old ones at any time, so it is important that all apps be able to handle the basic error codes.