Códigos de erro e tratamento de erro | Conceitos da API do Graph

Aplica-se a: API do Graph | Azure AD (Active Directory)

Os aplicativos cliente que usam a API do Graph do Azure AD (Active Directory) devem implementar a lógica de tratamento de erro para reagir da forma mais adequada possível a condições variáveis e para proporcionar a melhor experiência possível aos clientes. Este tópico aborda os tipos de erros retornados pela API do Graph do Azure AD, além de fornecer diretrizes gerais sobre como lidar com eles.

Tratando erros na API do Graph

Tipos de erros

Os erros da Graph API ocorrem nas seguintes categorias.

• Erros de cliente. Os erros de cliente são representados por códigos de status HTTP da série 400. Eles incluem objetos com valores inválidos, objetos que não têm propriedades ou valores de propriedade necessários, a tentativa de acessar um recurso inexistente, a tentativa de atualizar uma propriedade somente leitura e a omissão do token de autorização necessário. Para resolver esses erros, corrija o problema subjacente antes de repetir a solicitação.
• Erros de servidor. Os erros de servidor são representados por códigos de status HTTP da série 500, por exemplo uma falha de diretório temporária. A maioria desses erros é temporária e pode ser resolvida repetindo-se a solicitação.
• Erros de rede/protocolo. Uma variedade de erros relacionados à rede pode ocorrer durante o envio de uma solicitação ou o recebimento de uma resposta, como erros de resolução de nome de host, conexões fechadas prematuramente e erros de negociação SSL. A maioria desses erros não pode ser resolvida com uma repetição; é necessário solucionar o problema subjacente. No entanto, alguns erros, como as falhas de resolução de nome de host ou os erros relacionados com tempos limites, podem ser resolvidos repetindo-se a solicitação.

Estrutura da mensagem de erro

Os erros da Graph API têm um corpo formatado que consiste em um código de status HTTP, uma mensagem e valores. Use as propriedades do corpo do erro na sua lógica de tratamento de erro.

Observação: algumas respostas HTTP podem não incluir o corpo de resposta de código/mensagem/valores pois a solicitação é encaminhada por meio de serviços de proxy e gateway. Não se esqueça de incluir a lógica padrão capaz de manipular erros apenas com base no código do status HTTP.

Veja a seguir um exemplo de um erro HTTP 400 Request_BadRequest.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

Cada corpo de mensagem tem propriedades de código, mensagem e valores.

• Código: projete sua lógica de tratamento de erros para que ela seja ramificada com base no código.

  "code" : "Request_BadRequest"
  

• Mensagem: uma tupla linguagem/valor que representa uma mensagem de erro legível. O conteúdo está no campo de valor. No exemplo a seguir, a solicitação falha porque o valor da propriedade mailNickname está ausente.

  "message" : {
       "lang" : "en",
       "value" : "A value is required for property 'mailNickname' of resource 'Group'."
  }
  

• Valores: uma coleção de pares nome/valor que fornecem mais informações sobre a natureza da falha. No exemplo a seguir, não são incluídos valores.

  "values" : null
  

Referência do código de erro

Códigos de erro HTTP

A tabela a seguir lista os códigos de erro, as mensagens de erro e as ações do da API do Graph a serem considerados durante a correção dos erros.

Em geral, os erros HTTP 500 respondem às novas tentativas, distribuídas preferencialmente em intervalos de tempo cada vez mais longos (“repetir com um intervalo de retirada”) e com um fator de distribuição aleatório. Os erros da série 400 indicam um problema que deve ser solucionado antes de uma nova tentativa.

Recursos adicionais

• Referência da API do Graph do Azure AD